« back to all changes in this revision
Viewing changes to docs/xml/administration.xml
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Rémi Perrot
- Date: 2004-04-02 01:13:32 UTC
- Revision ID: james.westby@ubuntu.com-20040402011332-hxrg0n2szimd7d25
Tags: upstream-2.16.5
Import upstream version 2.16.5
- files added:
- contrib
- contrib/cmdline
- css
- docs
- docs/html
- docs/images
- docs/txt
- docs/xml
- t
- t/Support
- template
- template/en
- template/en/default
- template/en/default/account
- template/en/default/account/email
- template/en/default/account/password
- template/en/default/account/prefs
- template/en/default/admin
- template/en/default/admin/attachstatus
- template/en/default/attachment
- template/en/default/bug
- template/en/default/bug/activity
- template/en/default/bug/create
- template/en/default/bug/process
- template/en/default/bug/votes
- template/en/default/global
- template/en/default/list
- template/en/default/reports
- template/en/default/search
added
removed
docs/xml/administration.xml
1
<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
2
<chapter id="administration">
3
<title>Administering Bugzilla</title>
4
5
<section id="parameters">
6
<title>Bugzilla Configuration</title>
7
8
<para>Bugzilla is configured by changing various parameters, accessed
9
from the "Edit parameters" link in the page footer. Here are
10
some of the key parameters on that page. You should run down this
11
list and set them appropriately after installing Bugzilla.</para>
12
13
<indexterm>
14
<primary>checklist</primary>
15
</indexterm>
16
17
<procedure>
18
<step>
19
<para>
20
<command>maintainer</command>:
21
The maintainer parameter is the email address of the person
22
responsible for maintaining this
23
Bugzilla installation. The address need not be that of a valid Bugzilla
24
account.</para>
25
</step>
26
27
<step>
28
<para>
29
<command>urlbase</command>:
30
This parameter defines the fully qualified domain name and web
31
server path to your Bugzilla installation.</para>
32
33
<para>For example, if your Bugzilla query page is
34
<filename>http://www.foo.com/bugzilla/query.cgi</filename>,
35
set your <quote>urlbase</quote>
36
to <filename>http://www.foo.com/bugzilla/</filename>.</para>
37
</step>
38
39
<step>
40
<para>
41
<command>usebuggroups</command>:
42
This dictates whether or not to implement group-based security for
43
Bugzilla. If set, Bugzilla bugs can have an associated 'group',
44
defining which users are allowed to see and edit the
45
bug.</para>
46
47
<para>Set "usebuggroups" to "on"
48
<emphasis>only</emphasis>
49
if you may wish to restrict access to particular bugs to certain
50
groups of users. I suggest leaving
51
this parameter <emphasis>off</emphasis>
52
while initially testing your Bugzilla.</para>
53
</step>
54
55
<step>
56
<para>
57
<command>usebuggroupsentry</command>:
58
Bugzilla Products can have a group associated with them, so that
59
certain users can only see bugs in certain products. When this parameter
60
is set to <quote>on</quote>, this places all newly-created bugs in the
61
group for their product immediately.</para>
62
</step>
63
64
<step>
65
<para>
66
<command>shadowdb</command>:
67
You run into an interesting problem when Bugzilla reaches a
68
high level of continuous activity. MySQL supports only table-level
69
write locking. What this means is that if someone needs to make a
70
change to a bug, they will lock the entire table until the operation
71
is complete. Locking for write also blocks reads until the write is
72
complete. The
73
<quote>shadowdb</quote>
74
parameter was designed to get around this limitation. While only a
75
single user is allowed to write to a table at a time, reads can
76
continue unimpeded on a read-only shadow copy of the database.
77
Although your database size will double, a shadow database can cause
78
an enormous performance improvement when implemented on extremely
79
high-traffic Bugzilla databases.</para>
80
81
<para>
82
As a guide, mozilla.org began needing
83
<quote>shadowdb</quote>
84
when they reached around 40,000 Bugzilla users with several hundred
85
Bugzilla bug changes and comments per day.</para>
86
87
<para>The value of the parameter defines the name of the
88
shadow bug database.
89
Set "shadowdb" to e.g. "bug_shadowdb" if you will be running a
90
*very* large installation of Bugzilla.
91
<note>
92
<para>Enabling "shadowdb" can adversely affect the stability of
93
your installation of Bugzilla. You should regularly check that your
94
database is in sync. It is often advisable to force a shadow
95
database sync nightly via
96
<quote>cron</quote>.
97
</para>
98
</note>
99
</para>
100
101
<para>If you use the "shadowdb" option, it is only natural that you
102
should turn the "queryagainstshadowdb" option on as well. Otherwise
103
you are replicating data into a shadow database for no reason!</para>
104
105
</step>
106
107
<step>
108
<para>
109
<command>shutdownhtml</command>:
110
111
If you need to shut down Bugzilla to perform administration, enter
112
some descriptive HTML here and anyone who tries to use Bugzilla will
113
receive a page to that effect. Obviously, editparams.cgi will
114
still be accessible so you can remove the HTML and re-enable Bugzilla.
115
:-)
116
</para>
117
</step>
118
119
<step>
120
<para>
121
<command>passwordmail</command>:
122
123
Every time a user creates an account, the text of
124
this parameter (with substitutions) is sent to the new user along with
125
their password message.</para>
126
127
<para>Add any text you wish to the "passwordmail" parameter box. For
128
instance, many people choose to use this box to give a quick training
129
blurb about how to use Bugzilla at your site.</para>
130
</step>
131
132
<step>
133
<para>
134
<command>useqacontact</command>:
135
136
This allows you to define an email address for each component, in
137
addition
138
to that of the default owner, who will be sent carbon copies of
139
incoming bugs.</para>
140
</step>
141
<step>
142
<para>
143
<command>usestatuswhiteboard</command>:
144
This defines whether you wish to have a free-form, overwritable field
145
associated with each bug. The advantage of the Status Whiteboard is
146
that it can be deleted or modified with ease, and provides an
147
easily-searchable field for indexing some bugs that have some trait
148
in common.
149
</para>
150
</step>
151
152
<step>
153
<para>
154
<command>whinedays</command>:
155
Set this to the number of days you want to let bugs go
156
in the NEW or REOPENED state before notifying people they have
157
untouched new bugs. If you do not plan to use this feature, simply do
158
not set up the whining cron job described in the installation
159
instructions, or set this value to "0" (never whine).</para>
160
</step>
161
162
<step>
163
<para>
164
<command>commenton*</command>:
165
All these
166
fields allow you to dictate what changes can pass without comment,
167
and which must have a comment from the person who changed them.
168
Often, administrators will allow users to add themselves to the CC
169
list, accept bugs, or change the Status Whiteboard without adding a
170
comment as to their reasons for the change, yet require that most
171
other changes come with an explanation.</para>
172
173
<para>Set the "commenton" options according to your site policy. It
174
is a wise idea to require comments when users resolve, reassign, or
175
reopen bugs at the very least.
176
<note>
177
<para>It is generally far better to require a developer comment
178
when resolving bugs than not. Few things are more annoying to bug
179
database users than having a developer mark a bug "fixed" without
180
any comment as to what the fix was (or even that it was truly
181
fixed!)</para>
182
</note>
183
</para>
184
</step>
185
186
<step>
187
<para>
188
<command>supportwatchers</command>:
189
190
Turning on this option allows users to ask to receive copies of
191
all a particular other user's bug email. This is, of
192
course, subject to the groupset restrictions on the bug; if the
193
<quote>watcher</quote>
194
would not normally be allowed to view a bug, the watcher cannot get
195
around the system by setting herself up to watch the bugs of someone
196
with bugs outside her privileges. They would still only receive email
197
updates for those bugs she could normally view.</para>
198
</step>
199
</procedure>
200
</section>
201
202
<section id="useradmin">
203
<title>User Administration</title>
204
205
<section id="defaultuser">
206
<title>Creating the Default User</title>
207
208
<para>When you first run checksetup.pl after installing Bugzilla, it
209
will prompt you for the administrative username (email address) and
210
password for this "super user". If for some reason you delete
211
the "super user" account, re-running checksetup.pl will again prompt
212
you for this username and password.</para>
213
214
<tip>
215
<para>If you wish to add more administrative users, you must use the
216
MySQL interface. Run "mysql" from the command line, and use these
217
commands:
218
<simplelist>
219
<member>
220
<prompt>mysql></prompt>
221
<command>use bugs;</command>
222
</member>
223
224
<member>
225
<prompt>mysql></prompt>
226
227
<command>
228
update profiles set groupset=0x7fffffffffffffff where login_name =
229
"(user's login name)";
230
</command>
231
</member>
232
</simplelist>
233
</para>
234
235
<para>Yes, that is
236
<emphasis>fifteen</emphasis>
237
238
<quote>f</quote>
239
240
's. A whole lot of f-ing going on if you want to create a new
241
administator.</para>
242
</tip>
243
</section>
244
245
<section id="manageusers">
246
<title>Managing Other Users</title>
247
248
<section id="createnewusers">
249
<title>Creating new users</title>
250
251
<para>Your users can create their own user accounts by clicking the
252
"New Account" link at the bottom of each page (assuming they
253
aren't logged in as someone else already.) However, should you
254
desire to create user accounts ahead of time, here is how you do
255
it.</para>
256
257
<orderedlist>
258
<listitem>
259
<para>After logging in, click the "Users" link at the footer of
260
the query page, and then click "Add a new user".</para>
261
</listitem>
262
263
<listitem>
264
<para>Fill out the form presented. This page is self-explanatory.
265
When done, click "Submit".</para>
266
267
<note>
268
<para>Adding a user this way will
269
<emphasis>not</emphasis>
270
271
send an email informing them of their username and password.
272
While useful for creating dummy accounts (watchers which
273
shuttle mail to another system, for instance, or email
274
addresses which are a mailing list), in general it is
275
preferable to log out and use the
276
<quote>New Account</quote>
277
278
button to create users, as it will pre-populate all the
279
required fields and also notify the user of her account name
280
and password.</para>
281
</note>
282
</listitem>
283
</orderedlist>
284
</section>
285
286
<section id="modifyusers">
287
<title>Modifying Users</title>
288
289
<para>To see a specific user, search for their login name
290
in the box provided on the "Edit Users" page. To see all users,
291
leave the box blank.</para>
292
293
<para>You can search in different ways the listbox to the right
294
of the text entry box. You can match by
295
case-insensitive substring (the default),
296
regular expression, or a
297
<emphasis>reverse</emphasis>
298
regular expression match, which finds every user name which does NOT
299
match the regular expression. (Please see
300
the <command>man regexp</command>
301
manual page for details on regular expression syntax.)
302
</para>
303
304
<para>Once you have found your user, you can change the following
305
fields:</para>
306
307
<itemizedlist>
308
<listitem>
309
<para>
310
<emphasis>Login Name</emphasis>:
311
This is generally the user's full email address. However, if you
312
have are using the emailsuffix Param, this may just be the user's
313
login name. Note that users can now change their login names
314
themselves (to any valid email address.)
315
</para>
316
</listitem>
317
318
<listitem>
319
<para>
320
<emphasis>Real Name</emphasis>: The user's real name. Note that
321
Bugzilla does not require this to create an account.</para>
322
</listitem>
323
324
<listitem>
325
<para>
326
<emphasis>Password</emphasis>:
327
You can change the user's password here. Users can automatically
328
request a new password, so you shouldn't need to do this often.
329
If you want to disable an account, see Disable Text below.
330
</para>
331
</listitem>
332
333
<listitem>
334
<para>
335
<emphasis>Disable Text</emphasis>:
336
If you type anything in this box, including just a space, the
337
user is prevented from logging in, or making any changes to
338
bugs via the web interface.
339
The HTML you type in this box is presented to the user when
340
they attempt to perform these actions, and should explain
341
why the account was disabled.
342
<warning>
343
<para>Don't disable the administrator account!</para>
344
</warning>
345
346
<note>
347
<para>The user can still submit bugs via
348
the e-mail gateway, if you set it up, even if the disabled text
349
field is filled in. The e-mail gateway should
350
<emphasis>not</emphasis>
351
be enabled for secure installations of Bugzilla.</para>
352
</note>
353
</para>
354
</listitem>
355
356
<listitem>
357
<para>
358
<emphasis><groupname></emphasis>:
359
If you have created some groups, e.g. "securitysensitive", then
360
checkboxes will appear here to allow you to add users to, or
361
remove them from, these groups.
362
</para>
363
</listitem>
364
365
<listitem>
366
<para>
367
<emphasis>canconfirm</emphasis>:
368
This field is only used if you have enabled the "unconfirmed"
369
status. If you enable this for a user,
370
that user can then move bugs from "Unconfirmed" to a "Confirmed"
371
status (e.g.: "New" status).</para>
372
</listitem>
373
374
<listitem>
375
<para>
376
<emphasis>creategroups</emphasis>:
377
This option will allow a user to create and destroy groups in
378
Bugzilla.</para>
379
</listitem>
380
381
<listitem>
382
<para>
383
<emphasis>editbugs</emphasis>:
384
Unless a user has this bit set, they can only edit those bugs
385
for which they are the assignee or the reporter. Even if this
386
option is unchecked, users can still add comments to bugs.
387
</para>
388
</listitem>
389
390
<listitem>
391
<para>
392
<emphasis>editcomponents</emphasis>:
393
This flag allows a user to create new products and components,
394
as well as modify and destroy those that have no bugs associated
395
with them. If a product or component has bugs associated with it,
396
those bugs must be moved to a different product or component
397
before Bugzilla will allow them to be destroyed.
398
</para>
399
</listitem>
400
401
<listitem>
402
<para>
403
<emphasis>editkeywords</emphasis>:
404
If you use Bugzilla's keyword functionality, enabling this
405
feature allows a user to create and destroy keywords. As always,
406
the keywords for existing bugs containing the keyword the user
407
wishes to destroy must be changed before Bugzilla will allow it
408
to die.</para>
409
</listitem>
410
411
<listitem>
412
<para>
413
<emphasis>editusers</emphasis>:
414
This flag allows a user to do what you're doing right now: edit
415
other users. This will allow those with the right to do so to
416
remove administrator privileges from other users or grant them to
417
themselves. Enable with care.</para>
418
</listitem>
419
420
421
<listitem>
422
<para>
423
<emphasis>tweakparams</emphasis>:
424
This flag allows a user to change Bugzilla's Params
425
(using <filename>editparams.cgi</filename>.)</para>
426
</listitem>
427
428
<listitem>
429
<para>
430
<emphasis><productname></emphasis>:
431
This allows an administrator to specify the products in which
432
a user can see bugs. The user must still have the
433
"editbugs" privilege to edit bugs in these products.</para>
434
</listitem>
435
</itemizedlist>
436
</section>
437
</section>
438
</section>
439
440
<section id="programadmin">
441
<title>Product, Component, Milestone, and Version Administration</title>
442
443
<section id="products">
444
<title>Products</title>
445
446
<para>
447
<glossterm linkend="gloss-product" baseform="product">
448
Products</glossterm>
449
450
are the broadest category in Bugzilla, and tend to represent real-world
451
shipping products. E.g. if your company makes computer games,
452
you should have one product per game, perhaps a "Common" product for
453
units of technology used in multiple games, and maybe a few special
454
products (Website, Administration...)</para>
455
456
<para>Many of Bugzilla's settings are configurable on a per-product
457
basis. The number of "votes" available to users is set per-product,
458
as is the number of votes
459
required to move a bug automatically from the UNCONFIRMED status to the
460
NEW status.</para>
461
462
<para>To create a new product:</para>
463
464
<orderedlist>
465
<listitem>
466
<para>Select "products" from the footer</para>
467
468
</listitem>
469
470
<listitem>
471
<para>Select the "Add" link in the bottom right</para>
472
</listitem>
473
474
<listitem>
475
<para>Enter the name of the product and a description. The
476
Description field may contain HTML.</para>
477
</listitem>
478
</orderedlist>
479
480
<para>Don't worry about the "Closed for bug entry", "Maximum Votes
481
per person", "Maximum votes a person can put on a single bug",
482
"Number of votes a bug in this Product needs to automatically get out
483
of the UNCOMFIRMED state", and "Version" options yet. We'll cover
484
those in a few moments.
485
</para>
486
</section>
487
488
<section id="components">
489
<title>Components</title>
490
491
<para>Components are subsections of a Product. E.g. the computer game
492
you are designing may have a "UI"
493
component, an "API" component, a "Sound System" component, and a
494
"Plugins" component, each overseen by a different programmer. It
495
often makes sense to divide Components in Bugzilla according to the
496
natural divisions of responsibility within your Product or
497
company.</para>
498
499
<para>
500
Each component has a owner and (if you turned it on in the parameters),
501
a QA Contact. The owner should be the primary person who fixes bugs in
502
that component. The QA Contact should be the person who will ensure
503
these bugs are completely fixed. The Owner, QA Contact, and Reporter
504
will get email when new bugs are created in this Component and when
505
these bugs change. Default Owner and Default QA Contact fields only
506
dictate the
507
<emphasis>default assignments</emphasis>;
508
these can be changed on bug submission, or at any later point in
509
a bug's life.</para>
510
511
<para>To create a new Component:</para>
512
513
<orderedlist>
514
<listitem>
515
<para>Select the "Edit components" link from the "Edit product"
516
page</para>
517
</listitem>
518
519
<listitem>
520
<para>Select the "Add" link in the bottom right.</para>
521
</listitem>
522
523
<listitem>
524
<para>Fill out the "Component" field, a short "Description",
525
the "Initial Owner" and "Initial QA Contact" (if enabled.)
526
The Component and Description fields may contain HTML;
527
the "Initial Owner" field must be a login name
528
already existing in the database.
529
</para>
530
</listitem>
531
</orderedlist>
532
</section>
533
534
<section id="versions">
535
<title>Versions</title>
536
537
<para>Versions are the revisions of the product, such as "Flinders
538
3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select
539
field; the usual practice is to select the most recent version with
540
the bug.
541
</para>
542
543
<para>To create and edit Versions:</para>
544
545
<orderedlist>
546
<listitem>
547
<para>From the "Edit product" screen, select "Edit Versions"</para>
548
</listitem>
549
550
<listitem>
551
<para>You will notice that the product already has the default
552
version "undefined". Click the "Add" link in the bottom right.</para>
553
</listitem>
554
555
<listitem>
556
<para>Enter the name of the Version. This field takes text only.
557
Then click the "Add" button.</para>
558
</listitem>
559
560
</orderedlist>
561
</section>
562
563
<section id="milestones">
564
<title>Milestones</title>
565
566
<para>Milestones are "targets" that you plan to get a bug fixed by. For
567
example, you have a bug that you plan to fix for your 3.0 release, it
568
would be assigned the milestone of 3.0.</para>
569
570
<note>
571
<para>Milestone options will only appear for a Product if you turned
572
on the "usetargetmilestone" Param in the "Edit Parameters" screen.
573
</para>
574
</note>
575
576
<para>To create new Milestones, set Default Milestones, and set
577
Milestone URL:</para>
578
579
<orderedlist>
580
<listitem>
581
<para>Select "Edit milestones" from the "Edit product" page.</para>
582
</listitem>
583
584
<listitem>
585
<para>Select "Add" in the bottom right corner.
586
text</para>
587
</listitem>
588
589
<listitem>
590
<para>Enter the name of the Milestone in the "Milestone" field. You
591
can optionally set the "sortkey", which is a positive or negative
592
number (-255 to 255) that defines where in the list this particular
593
milestone appears. This is because milestones often do not
594
occur in alphanumeric order For example, "Future" might be
595
after "Release 1.2". Select "Add".</para>
596
</listitem>
597
598
<listitem>
599
<para>From the Edit product screen, you can enter the URL of a
600
page which gives information about your milestones and what
601
they mean. </para>
602
603
<tip>
604
<para>If you want your milestone document to be restricted so
605
that it can only be viewed by people in a particular Bugzilla
606
group, the best way is to attach the document to a bug in that
607
group, and make the URL the URL of that attachment.</para>
608
</tip>
609
</listitem>
610
</orderedlist>
611
</section>
612
</section>
613
614
<section id="voting">
615
<title>Voting</title>
616
617
<para>Voting allows users to be given a pot of votes which they can allocate
618
to bugs, to indicate that they'd like them fixed.
619
This allows developers to gauge
620
user need for a particular enhancement or bugfix. By allowing bugs with
621
a certain number of votes to automatically move from "UNCONFIRMED" to
622
"NEW", users of the bug system can help high-priority bugs garner
623
attention so they don't sit for a long time awaiting triage.</para>
624
625
<para>To modify Voting settings:</para>
626
627
<orderedlist>
628
<listitem>
629
<para>Navigate to the "Edit product" screen for the Product you
630
wish to modify</para>
631
</listitem>
632
633
<listitem>
634
<para><emphasis>Maximum Votes per person</emphasis>:
635
Setting this field to "0" disables voting.</para>
636
</listitem>
637
638
<listitem>
639
<para><emphasis>Maximum Votes a person can put on a single
640
bug"</emphasis>:
641
It should probably be some number lower than the
642
"Maximum votes per person". Don't set this field to "0" if
643
"Maximum votes per person" is non-zero; that doesn't make
644
any sense.</para>
645
</listitem>
646
647
<listitem>
648
<para><emphasis>Number of votes a bug in this product needs to
649
automatically get out of the UNCONFIRMED state</emphasis>:
650
Setting this field to "0" disables the automatic move of
651
bugs from UNCONFIRMED to NEW.
652
</para>
653
</listitem>
654
655
<listitem>
656
<para>Once you have adjusted the values to your preference, click
657
"Update".</para>
658
</listitem>
659
</orderedlist>
660
</section>
661
662
<section id="groups">
663
<title>Groups and Group Security</title>
664
665
<para>Groups allow the administrator
666
to isolate bugs or products that should only be seen by certain people.
667
There are two types of group - Generic Groups, and Product-Based Groups.
668
</para>
669
670
<para>
671
Product-Based Groups are matched with products, and allow you to restrict
672
access to bugs on a per-product basis. They are enabled using the
673
usebuggroups Param. Turning on the usebuggroupsentry
674
Param will mean bugs automatically get added to their product group when
675
filed.
676
</para>
677
678
<para>
679
Generic Groups have no special relationship to products;
680
you create them, and put bugs in them
681
as required. One example of the use of Generic Groups
682
is Mozilla's "Security" group,
683
into which security-sensitive bugs are placed until fixed. Only the
684
Mozilla Security Team are members of this group.
685
</para>
686
687
<para>To create Generic Groups:</para>
688
689
<orderedlist>
690
<listitem>
691
<para>Select the "groups"
692
link in the footer.</para>
693
</listitem>
694
695
<listitem>
696
<para>Take a moment to understand the instructions on the "Edit
697
Groups" screen, then select the "Add Group" link.</para>
698
</listitem>
699
700
<listitem>
701
<para>Fill out the "New Name", "New Description", and
702
"New User RegExp" fields. "New User RegExp" allows you to automatically
703
place all users who fulfill the Regular Expression into the new group.
704
When you have finished, click "Add".</para>
705
</listitem>
706
</orderedlist>
707
708
<para>To use Product-Based Groups:</para>
709
710
<orderedlist>
711
<listitem>
712
<para>Turn on "usebuggroups" and "usebuggroupsentry" in the "Edit
713
Parameters" screen.</para>
714
715
<warning>
716
<para>XXX is this still true?
717
"usebuggroupsentry" has the capacity to prevent the
718
administrative user from directly altering bugs because of
719
conflicting group permissions. If you plan on using
720
"usebuggroupsentry", you should plan on restricting
721
administrative account usage to administrative duties only. In
722
other words, manage bugs with an unpriveleged user account, and
723
manage users, groups, Products, etc. with the administrative
724
account.</para>
725
</warning>
726
</listitem>
727
728
<listitem>
729
<para>In future, when you create a Product, a matching group will be
730
automatically created. If you need to add a Product Group to
731
a Product which was created before you turned on usebuggroups,
732
then simply create a new group, as outlined above, with the
733
same name as the Product.</para>
734
</listitem>
735
</orderedlist>
736
737
<warning>
738
<para>Bugzilla currently has a limit of 64 groups per installation. If
739
you have more than about 50 products, you should consider
740
running multiple Bugzillas. Ask in the newsgroup for other
741
suggestions for working around this restriction.</para>
742
</warning>
743
744
<para>
745
Note that group permissions are such that you need to be a member
746
of <emphasis>all</emphasis> the groups a bug is in, for whatever
747
reason, to see that bug.
748
</para>
749
</section>
750
751
<section id="security">
752
<title>Bugzilla Security</title>
753
754
<warning>
755
<para>Poorly-configured MySQL and Bugzilla installations have
756
given attackers full access to systems in the past. Please take these
757
guidelines seriously, even for Bugzilla machines hidden away behind
758
your firewall. 80% of all computer trespassers are insiders, not
759
anonymous crackers.</para>
760
</warning>
761
762
<note>
763
<para>These instructions must, of necessity, be somewhat vague since
764
Bugzilla runs on so many different platforms. If you have refinements
765
of these directions, please submit a bug to &bzg-bugs;.
766
</para>
767
</note>
768
769
<warning>
770
<para>This is not meant to be a comprehensive list of every possible
771
security issue regarding the tools mentioned in this section. There is
772
no subsitute for reading the information written by the authors of any
773
software running on your system.
774
</para>
775
</warning>
776
777
<section id="security-networking">
778
<title>TCP/IP Ports</title>
779
780
<!-- TODO: Make this make sense (TCP/IP) -->
781
<para>TCP/IP defines 65,000 some ports for trafic. Of those, Bugzilla
782
only needs 1... 2 if you need to use features that require e-mail such
783
as bug moving or the e-mail interface from contrib. You should audit
784
your server and make sure that you aren't listening on any ports you
785
don't need to be. You may also wish to use some kind of firewall
786
software to be sure that trafic can only be recieved on ports you
787
specify.
788
</para>
789
</section>
790
791
<section id="security-mysql">
792
<title>MySQL</title>
793
794
<para>MySQL ships by default with many settings that should be changed.
795
By defaults it allows anybody to connect from localhost without a
796
password and have full administrative capabilities. It also defaults to
797
not have a root password (this is <emphasis>not</emphasis> the same as
798
the system root). Also, many installations default to running
799
<application>mysqld</application> as the system root.
800
</para>
801
802
<orderedlist>
803
<listitem>
804
<para>Make sure you are running at least version 3.22.32 of MySQL
805
as earlier versions had notable security holes.
806
</para>
807
</listitem>
808
809
<listitem>
810
<para>Consult the documentation that came with your system for
811
information on making <application>mysqld</application> run as an
812
unprivleged user.
813
</para>
814
</listitem>
815
816
<listitem>
817
<para>You should also be sure to disable the anonymous user account
818
and set a password for the root user. This is accomplished using the
819
following commands:
820
</para>
821
<programlisting>
822
<prompt>bash$</prompt> mysql mysql
823
<prompt>mysql></prompt> DELETE FROM user WHERE user = '';
824
<prompt>mysql></prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root';
825
<prompt>mysql></prompt> FLUSH PRIVILEGES;
826
</programlisting>
827
<para>From this point forward you will need to use
828
<command>mysql -u root -p</command> and enter
829
<replaceable>new_password</replaceable> when prompted when using the
830
mysql client.
831
</para>
832
</listitem>
833
834
<listitem>
835
<para>If you run MySQL on the same machine as your httpd server, you
836
should consider disabling networking from within MySQL by adding
837
the following to your <filename>/etc/my.conf</filename>:
838
</para>
839
<programlisting>
840
[myslqd]
841
# Prevent network access to MySQL.
842
skip-networking
843
</programlisting>
844
</listitem>
845
846
<listitem>
847
<para>You may also consider running MySQL, or even all of Bugzilla
848
in a chroot jail; however, instructions for doing that are beyond
849
the scope of this document.
850
</para>
851
</listitem>
852
853
</orderedlist>
854
855
</section>
856
857
<section id="security-daemon">
858
<title>Daemon Accounts</title>
859
860
<para>Many daemons, such as Apache's httpd and MySQL's mysqld default to
861
running as either <quote>root</quote> or <quote>nobody</quote>. Running
862
as <quote>root</quote> introduces obvious security problems, but the
863
problems introduced by running everything as <quote>nobody</quote> may
864
not be so obvious. Basically, if you're running every daemon as
865
<quote>nobody</quote> and one of them gets comprimised, they all get
866
comprimised. For this reason it is recommended that you create a user
867
account for each daemon.
868
</para>
869
870
<note>
871
<para>You will need to set the <varname>webservergroup</varname> to
872
the group you created for your webserver to run as in
873
<filename>localconfig</filename>. This will allow
874
<command>./checksetup.pl</command> to better adjust the file
875
permissions on your Bugzilla install so as to not require making
876
anything world-writable.
877
</para>
878
</note>
879
880
</section>
881
882
<section id="security-access">
883
<title>Web Server Access Controls</title>
884
885
<para>There are many files that are placed in the Bugzilla directory
886
area that should not be accessable from the web. Because of the way
887
Bugzilla is currently layed out, the list of what should and should
888
not be accessible is rather complicated. A new installation method
889
is currently in the works which should solve this by allowing files
890
that shouldn't be accessible from the web to be placed in directory
891
outside the webroot. See
892
<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=44659">bug
893
44659</ulink> for more information.
894
</para>
895
896
<itemizedlist spacing="compact">
897
<listitem>
898
<para>In the main Bugzilla directory, you should:</para>
899
<itemizedlist spacing="compact">
900
<listitem>
901
<para>Block:
902
<simplelist type="inline">
903
<member><filename>*.pl</filename></member>
904
<member><filename>*localconfig*</filename></member>
905
<member><filename>runtests.sh</filename></member>
906
<member><filename>processmail</filename></member>
907
<member><filename>syncshadowdb</filename></member>
908
</simplelist>
909
</para>
910
</listitem>
911
<listitem>
912
<para>But allow:
913
<simplelist type="inline">
914
<member><filename>localconfig.js</filename></member>
915
<member><filename>localconfig.rdf</filename></member>
916
</simplelist>
917
</para>
918
</listitem>
919
</itemizedlist>
920
</listitem>
921
922
<listitem>
923
<para>In <filename class="directory">data</filename>:</para>
924
<itemizedlist spacing="compact">
925
<listitem>
926
<para>Block everything</para>
927
</listitem>
928
<listitem>
929
<para>But allow:
930
<simplelist type="inline">
931
<member><filename>duplicates.rdf</filename></member>
932
</simplelist>
933
</para>
934
</listitem>
935
</itemizedlist>
936
</listitem>
937
938
<listitem>
939
<para>In <filename class="directory">data/webdot</filename>:</para>
940
<itemizedlist spacing="compact">
941
<listitem>
942
<para>If you use a remote webdot server:</para>
943
<itemizedlist spacing="compact">
944
<listitem>
945
<para>Block everything</para>
946
</listitem>
947
<listitem>
948
<para>But allow
949
<simplelist type="inline">
950
<member><filename>*.dot</filename></member>
951
</simplelist>
952
only for the remote webdot server</para>
953
</listitem>
954
</itemizedlist>
955
</listitem>
956
<listitem>
957
<para>Otherwise, if you use a local GraphViz:</para>
958
<itemizedlist spacing="compact">
959
<listitem>
960
<para>Block everything</para>
961
</listitem>
962
<listitem>
963
<para>But allow:
964
<simplelist type="inline">
965
<member><filename>*.png</filename></member>
966
<member><filename>*.gif</filename></member>
967
<member><filename>*.jpg</filename></member>
968
<member><filename>*.map</filename></member>
969
</simplelist>
970
</para>
971
</listitem>
972
</itemizedlist>
973
</listitem>
974
<listitem>
975
<para>And if you don't use any dot:</para>
976
<itemizedlist spacing="compact">
977
<listitem>
978
<para>Block everything</para>
979
</listitem>
980
</itemizedlist>
981
</listitem>
982
</itemizedlist>
983
</listitem>
984
985
<listitem>
986
<para>In <filename class="directory">Bugzilla</filename>:</para>
987
<itemizedlist spacing="compact">
988
<listitem>
989
<para>Block everything</para>
990
</listitem>
991
</itemizedlist>
992
</listitem>
993
994
<listitem>
995
<para>In <filename class="directory">template</filename>:</para>
996
<itemizedlist spacing="compact">
997
<listitem>
998
<para>Block everything</para>
999
</listitem>
1000
</itemizedlist>
1001
</listitem>
1002
</itemizedlist>
1003
1004
<tip>
1005
<para>Bugzilla ships with the ability to generate
1006
<filename>.htaccess</filename> files instructing Apache which files
1007
should and should not be accessible.
1008
</para>
1009
</tip>
1010
1011
<para>You should test to make sure that the files mentioned above are
1012
not accessible from the Internet, especially your
1013
<filename>localconfig</filename> file which contains your database
1014
password. To test, simply point your web browser at the file; for
1015
example, to test mozilla.org's installation, we'd try to access
1016
<ulink url="http://bugzilla.mozilla.org/localconfig"/>. You should
1017
get a <errorcode>403</errorcode> <errorname>Forbidden</errorname>
1018
error.
1019
</para>
1020
1021
<caution>
1022
<para>Not following the instructions in this section, including
1023
testing, may result in sensitive information being globally
1024
accessible.
1025
</para>
1026
</caution>
1027
1028
</section>
1029
1030
</section>
1031
1032
<section id="cust-templates">
1033
<title>Template Customisation</title>
1034
1035
<para>
1036
One of the large changes for 2.16 was the templatisation of the
1037
entire user-facing UI, using the
1038
<ulink url="http://www.template-toolkit.org">Template Toolkit</ulink>.
1039
Administrators can now configure the look and feel of Bugzilla without
1040
having to edit Perl files or face the nightmare of massive merge
1041
conflicts when they upgrade to a newer version in the future.
1042
</para>
1043
1044
<para>
1045
Templatisation also makes localised versions of Bugzilla possible,
1046
for the first time. In the future, a Bugzilla installation may
1047
have templates installed for multiple localisations, and select
1048
which ones to use based on the user's browser language setting.
1049
</para>
1050
1051
<section>
1052
<title>What to Edit</title>
1053
<para>
1054
There are two different ways of editing of Bugzilla's templates,
1055
and which you use depends mainly on how you upgrade Bugzilla. The
1056
template directory structure is that there's a top level directory,
1057
<filename>template</filename>, which contains a directory for
1058
each installed localisation. The default English templates are
1059
therefore in <filename>en</filename>. Underneath that, there
1060
is the <filename>default</filename> directory and optionally the
1061
<filename>custom</filename> directory. The <filename>default</filename>
1062
directory contains all the templates shipped with Bugzilla, whereas
1063
the <filename>custom</filename> directory does not exist at first and
1064
must be created if you want to use it.
1065
</para>
1066
1067
<para>
1068
The first method of making customisations is to directly edit the
1069
templates in <filename>template/en/default</filename>. This is
1070
probably the best method for small changes if you are going to use
1071
the CVS method of upgrading, because if you then execute a
1072
<command>cvs update</command>, any template fixes will get
1073
automagically merged into your modified versions.
1074
</para>
1075
1076
<para>
1077
If you use this method, your installation will break if CVS conflicts
1078
occur.
1079
</para>
1080
1081
<para>
1082
The other method is to copy the templates into a mirrored directory
1083
structure under <filename>template/en/custom</filename>. The templates
1084
in this directory automatically override those in default.
1085
This is the technique you
1086
need to use if you use the overwriting method of upgrade, because
1087
otherwise your changes will be lost. This method is also better if
1088
you are using the CVS method of upgrading and are going to make major
1089
changes, because it is guaranteed that the contents of this directory
1090
will not be touched during an upgrade, and you can then decide whether
1091
to continue using your own templates, or make the effort to merge your
1092
changes into the new versions by hand.
1093
</para>
1094
1095
<para>
1096
If you use this method, your installation may break if incompatible
1097
changes are made to the template interface. If such changes are made
1098
they will be documented in the release notes, provided you are using a
1099
stable release of Bugzilla. If you use using unstable code, you will
1100
need to deal with this one yourself, although if possible the changes
1101
will be mentioned before they occur in the deprecations section of the
1102
previous stable release's release notes.
1103
</para>
1104
1105
<note>
1106
<para>
1107
Don't directly edit the compiled templates in
1108
<filename class="directory">data/template/*</filename> - your
1109
changes will be lost when Template Toolkit recompiles them.
1110
</para>
1111
</note>
1112
1113
<note>
1114
<para>It is recommended that you run <command>./checksetup.pl</command>
1115
after any template edits, especially if you've created a new file in
1116
the <filename class="directory">custom</filename> directory.
1117
</para>
1118
</note>
1119
</section>
1120
1121
<section>
1122
<title>How To Edit Templates</title>
1123
1124
<para>
1125
The syntax of the Template Toolkit language is beyond the scope of
1126
this guide. It's reasonably easy to pick up by looking at the current
1127
templates; or, you can read the manual, available on the
1128
<ulink url="http://www.template-toolkit.org">Template Toolkit home
1129
page</ulink>. However, you should particularly remember (for security
1130
reasons) to always HTML filter things which come from the database or
1131
user input, to prevent cross-site scripting attacks.
1132
</para>
1133
1134
<para>
1135
However, one thing you should take particular care about is the need
1136
to properly HTML filter data that has been passed into the template.
1137
This means that if the data can possibly contain special HTML characters
1138
such as <, and the data was not intended to be HTML, they need to be
1139
converted to entity form, ie &lt;. You use the 'html' filter in the
1140
Template Toolkit to do this. If you fail to do this, you may open up
1141
your installation to cross-site scripting attacks.
1142
</para>
1143
1144
<para>
1145
Also note that Bugzilla adds a few filters of its own, that are not
1146
in standard Template Toolkit. In particular, the 'url_quote' filter
1147
can convert characters that are illegal or have special meaning in URLs,
1148
such as &, to the encoded form, ie %26. This actually encodes most
1149
characters (but not the common ones such as letters and numbers and so
1150
on), including the HTML-special characters, so there's never a need to
1151
HTML filter afterwards.
1152
</para>
1153
1154
<para>
1155
Editing templates is a good way of doing a "poor man's custom fields".
1156
For example, if you don't use the Status Whiteboard, but want to have
1157
a free-form text entry box for "Build Identifier", then you can just
1158
edit the templates to change the field labels. It's still be called
1159
status_whiteboard internally, but your users don't need to know that.
1160
</para>
1161
1162
<note>
1163
<para>
1164
If you are making template changes that you intend on submitting back
1165
for inclusion in standard Bugzilla, you should read the relevant
1166
sections of the
1167
<ulink url="http://www.bugzilla.org/developerguide.html">Developers'
1168
Guide</ulink>.
1169
</para>
1170
</note>
1171
</section>
1172
1173
1174
<section>
1175
<title>Template Formats</title>
1176
1177
<para>
1178
Some CGIs have the ability to use more than one template. For
1179
example, buglist.cgi can output bug lists as RDF or two
1180
different forms of HTML (complex and simple). (Try this out
1181
by appending <filename>&format=simple</filename> to a buglist.cgi
1182
URL on your Bugzilla installation.) This
1183
mechanism, called template 'formats', is extensible.
1184
</para>
1185
1186
<para>
1187
To see if a CGI supports multiple output formats, grep the
1188
CGI for "ValidateOutputFormat". If it's not present, adding
1189
multiple format support isn't too hard - see how it's done in
1190
other CGIs.
1191
</para>
1192
1193
<para>
1194
To make a new format template for a CGI which supports this,
1195
open a current template for
1196
that CGI and take note of the INTERFACE comment (if present.) This
1197
comment defines what variables are passed into this template. If
1198
there isn't one, I'm afraid you'll have to read the template and
1199
the code to find out what information you get.
1200
</para>
1201
1202
<para>
1203
Write your template in whatever markup or text style is appropriate.
1204
</para>
1205
1206
<para>
1207
You now need to decide what content type you want your template
1208
served as. Open up the <filename>localconfig</filename> file and find the
1209
<filename>$contenttypes</filename>
1210
variable. If your content type is not there, add it. Remember
1211
the three- or four-letter tag assigned to you content type.
1212
This tag will be part of the template filename.
1213
</para>
1214
1215
<para>
1216
Save the template as <filename><stubname>-<formatname>.<contenttypetag>.tmpl</filename>.
1217
Try out the template by calling the CGI as
1218
<filename><cginame>.cgi?format=<formatname></filename> .
1219
</para>
1220
</section>
1221
1222
1223
<section>
1224
<title>Particular Templates</title>
1225
1226
<para>
1227
There are a few templates you may be particularly interested in
1228
customising for your installation.
1229
</para>
1230
1231
<para>
1232
<command>index.html.tmpl</command>:
1233
This is the Bugzilla front page.
1234
</para>
1235
1236
<para>
1237
<command>global/header.html.tmpl</command>:
1238
This defines the header that goes on all Bugzilla pages.
1239
The header includes the banner, which is what appears to users
1240
and is probably what you want to edit instead. However the
1241
header also includes the HTML HEAD section, so you could for
1242
example add a stylesheet or META tag by editing the header.
1243
</para>
1244
1245
<para>
1246
<command>global/banner.html.tmpl</command>:
1247
This contains the "banner", the part of the header that appears
1248
at the top of all Bugzilla pages. The default banner is reasonably
1249
barren, so you'll probably want to customise this to give your
1250
installation a distinctive look and feel. It is recommended you
1251
preserve the Bugzilla version number in some form so the version
1252
you are running can be determined, and users know what docs to read.
1253
</para>
1254
1255
<para>
1256
<command>global/footer.html.tmpl</command>:
1257
This defines the footer that goes on all Bugzilla pages. Editing
1258
this is another way to quickly get a distinctive look and feel for
1259
your Bugzilla installation.
1260
</para>
1261
1262
<para>
1263
<command>bug/create/user-message.html.tmpl</command>:
1264
This is a message that appears near the top of the bug reporting page.
1265
By modifying this, you can tell your users how they should report
1266
bugs.
1267
</para>
1268
1269
<para>
1270
<command>bug/create/create.html.tmpl</command> and
1271
<command>bug/create/comment.txt.tmpl</command>:
1272
You may wish to get bug submitters to give certain bits of structured
1273
information, each in a separate input widget, for which there is not a
1274
field in the database. The bug entry system has been designed in an
1275
extensible fashion to enable you to define arbitrary fields and widgets,
1276
and have their values appear formatted in the initial
1277
Description, rather than in database fields. An example of this
1278
is the mozilla.org
1279
<ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?format=guided">guided
1280
bug submission form</ulink>.
1281
</para>
1282
1283
<para>
1284
To make this work, create a custom template for
1285
<filename>enter_bug.cgi</filename> (the default template, on which you
1286
could base it, is <filename>create.html.tmpl</filename>),
1287
and either call it <filename>create.html.tmpl</filename> or use a format and
1288
call it <filename>create-<formatname>.html.tmpl</filename>.
1289
Put it in the <filename class="directory">custom/bug/create</filename>
1290
directory. In it, add widgets for each piece of information you'd like
1291
collected - such as a build number, or set of steps to reproduce.
1292
</para>
1293
1294
<para>
1295
Then, create a template like
1296
<filename>custom/bug/create/comment.txt.tmpl</filename>, also named
1297
after your format if you are using one, which
1298
references the form fields you have created. When a bug report is
1299
submitted, the initial comment attached to the bug report will be
1300
formatted according to the layout of this template.
1301
</para>
1302
1303
<para>
1304
For example, if your enter_bug template had a field
1305
<programlisting><input type="text" name="buildid" size="30"></programlisting>
1306
and then your comment.txt.tmpl had
1307
<programlisting>BuildID: [% form.buildid %]</programlisting>
1308
then
1309
<programlisting>BuildID: 20020303</programlisting>
1310
would appear in the initial checkin comment.
1311
</para>
1312
</section>
1313
1314
</section>
1315
1316
<section id="upgrading">
1317
<title>Upgrading to New Releases</title>
1318
1319
<para>Upgrading Bugzilla is something we all want to do from time to time,
1320
be it to get new features or pick up the latest security fix. How easy
1321
it is to update depends on a few factors.
1322
</para>
1323
1324
<itemizedlist>
1325
<listitem>
1326
<para>If the new version is a revision or a new point release</para>
1327
</listitem>
1328
<listitem>
1329
<para>How many, if any, local changes have been made</para>
1330
</listitem>
1331
</itemizedlist>
1332
1333
<para>There are also three different methods to upgrade your installation.
1334
</para>
1335
1336
<orderedlist>
1337
<listitem>
1338
<para>Using CVS (<xref linkend="upgrade-cvs"/>)</para>
1339
</listitem>
1340
<listitem>
1341
<para>Downloading a new tarball (<xref linkend="upgrade-tarball"/>)</para>
1342
</listitem>
1343
<listitem>
1344
<para>Applying the relevant patches (<xref linkend="upgrade-patches"/>)</para>
1345
</listitem>
1346
</orderedlist>
1347
1348
<para>Which options are available to you may depend on how large a jump
1349
you are making and/or your network configuration.
1350
</para>
1351
1352
<para>Revisions are normally released to fix security vulnerabilities
1353
and are distinguished by an increase in the third number. For example,
1354
when 2.16.2 was released, it was a revision to 2.16.1.
1355
</para>
1356
1357
<para>Point releases are normally released when the Bugzilla team feels
1358
that there has been a significant amount of progress made between the
1359
last point release and the current time. These are often proceeded by a
1360
stabilization period and release candidates, however the use of
1361
development versions or release candidates is beyond the scope of this
1362
document. Point releases can be distinguished by an increase in the
1363
second number, or minor version. For example, 2.16.2 is a newer point
1364
release than 2.14.5.
1365
</para>
1366
1367
<para>The examples in this section are written as if you were updating
1368
to version 2.16.2. The procedures are the same regardless if you are
1369
updating to a new point release or a new revision. However, the chance
1370
of running into trouble increases when upgrading to a new point release,
1371
escpecially if you've made local changes.
1372
</para>
1373
1374
<para>These examples also assume that your Bugzilla installation is at
1375
<filename>/var/www/html/bugzilla</filename>. If that is not the case,
1376
simply substitute the proper paths where appropriate.
1377
</para>
1378
1379
<example id="upgrade-cvs">
1380
<title>Upgrading using CVS</title>
1381
1382
<para>Every release of Bugzilla, whether it is a revision or a point
1383
release, is tagged in CVS. Also, every tarball we have distributed
1384
since version 2.12 has been primed for using CVS. This does, however,
1385
require that you are able to access cvs-mirror.mozilla.org on port
1386
2401.
1387
1388
<tip>
1389
<para>If you can do this, updating using CVS is probably the most
1390
painless method, especially if you have a lot of local changes.
1391
</para>
1392
</tip>
1393
</para>
1394
1395
<programlisting>
1396
bash$ <command>cd /var/www/html/bugzilla</command>
1397
bash$ <command>cvs login</command>
1398
Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot
1399
CVS password: <command>anonymous</command>
1400
bash$ <command>cvs -q update -r BUGZILLA-2_16_2 -dP</command>
1401
P checksetup.pl
1402
P collectstats.pl
1403
P globals.pl
1404
P docs/rel_notes.txt
1405
P template/en/default/list/quips.html.tmpl
1406
</programlisting>
1407
1408
<para>
1409
<caution>
1410
<para>If a line in the output from <command>cvs update</command>
1411
begins with a <computeroutput>C</computeroutput> that represents a
1412
file with local changes that CVS was unable to properly merge. You
1413
need to resolve these conflicts manually before Bugzilla (or at
1414
least the portion using that file) will be usable.
1415
</para>
1416
</caution>
1417
1418
<note>
1419
<para>You also need to run <command>./checksetup.pl</command>
1420
before your Bugzilla upgrade will be complete.
1421
</para>
1422
</note>
1423
</para>
1424
</example>
1425
1426
<example id="upgrade-tarball">
1427
<title>Upgrading using the tarball</title>
1428
1429
<para>If you are unable or unwilling to use CVS, another option that's
1430
always available is to download the latest tarball. This is the most
1431
difficult option to use, especially if you have local changes.
1432
</para>
1433
1434
<programlisting>
1435
bash$ <command>cd /var/www/html</command>
1436
bash$ <command>wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.2.tar.gz</command>
1437
<emphasis>Output omitted</emphasis>
1438
bash$ <command>tar xzvf bugzilla-2.16.2.tar.gz</command>
1439
bugzilla-2.16.2/
1440
bugzilla-2.16.2/.cvsignore
1441
bugzilla-2.16.2/1x1.gif
1442
<emphasis>Output truncated</emphasis>
1443
bash$ <command>cd bugzilla-2.16.2</command>
1444
bash$ <command>cp ../bugzilla/localconfig* .</command>
1445
bash$ <command>cp -r ../bugzilla/data .</command>
1446
bash$ <command>cd ..</command>
1447
bash$ <command>mv bugzilla bugzilla.old</command>
1448
bash$ <command>mv bugzilla-2.16.2 bugzilla</command>
1449
bash$ <command>cd bugzilla</command>
1450
bash$ <command>./checksetup.pl</command>
1451
<emphasis>Output omitted</emphasis>
1452
</programlisting>
1453
1454
<para>
1455
<warning>
1456
<para>The <command>cp</command> commands both end with periods which
1457
is a very important detail, it tells the shell that the destination
1458
directory is the current working directory. Also, the period at the
1459
beginning of the <command>./checksetup.pl</command> is important and
1460
can not be omitted.
1461
</para>
1462
</warning>
1463
1464
<note>
1465
<para>You will now have to reapply any changes you have made to your
1466
local installation manually.
1467
</para>
1468
</note>
1469
</para>
1470
</example>
1471
1472
<example id="upgrade-patches">
1473
<title>Upgrading using patches</title>
1474
1475
<para>The Bugzilla team will normally make a patch file available for
1476
revisions to go from the most recent revision to the new one. You could
1477
also read the release notes and grab the patches attached to the
1478
mentioned bug, but it is safer to use the released patch file as
1479
sometimes patches get changed before they get checked in (for minor
1480
spelling fixes and the like). It is also theorectically possible to
1481
scour the fixed bug list and pick and choose which patches to apply
1482
from a point release, but this is not recommended either as what you'll
1483
end up with is a hodge podge Bugzilla that isn't really any version.
1484
This would also make it more difficult to upgrade in the future.
1485
</para>
1486
1487
<programlisting>
1488
bash$ <command>cd /var/www/html/bugzilla</command>
1489
bash$ <command>wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.1-to-2.16.2.diff.gz</command>
1490
<emphasis>Output omitted</emphasis>
1491
bash$ <command>gunzip bugzilla-2.16.1-to-2.16.2.diff.gz</command>
1492
bash$ <command>patch -p1 < bugzilla-2.16.1-to-2.16.2.diff</command>
1493
patching file checksetup.pl
1494
patching file collectstats.pl
1495
patching file globals.pl
1496
</programlisting>
1497
1498
<para>
1499
<caution>
1500
<para>If you do this, beware that this doesn't change the entires in
1501
your <filename id="dir">CVS</filename> directory so it may make
1502
updates using CVS (<xref linkend="upgrade-cvs"/>) more difficult in the
1503
future.
1504
</para>
1505
</caution>
1506
</para>
1507
</example>
1508
1509
</section>
1510
1511
<!-- Integrating Bugzilla with Third-Party Tools -->
1512
&integration;
1513
1514
</chapter>
1515
1516
<!-- Keep this comment at the end of the file
1517
Local variables:
1518
mode: sgml
1519
sgml-always-quote-attributes:t
1520
sgml-auto-insert-required-elements:t
1521
sgml-balanced-tag-edit:t
1522
sgml-exposed-tags:nil
1523
sgml-general-insert-case:lower
1524
sgml-indent-data:t
1525
sgml-indent-step:2
1526
sgml-local-catalogs:nil
1527
sgml-local-ecat-files:nil
1528
sgml-minimize-attributes:nil
1529
sgml-namecase-general:t
1530
sgml-omittag:t
1531
sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
1532
sgml-shorttag:t
1533
sgml-tag-region-if-active:t
1534
End:
1535
-->
1536
Loggerhead is a web-based interface for Breezy
Version: 2.0.1