]> git.ipfire.org Git - thirdparty/bugzilla.git/commitdiff
Bug 256019 - The documentation was unclear regarding what to do if the administrator...
authorjake%bugzilla.org <>
Sat, 11 Dec 2004 19:32:16 +0000 (19:32 +0000)
committerjake%bugzilla.org <>
Sat, 11 Dec 2004 19:32:16 +0000 (19:32 +0000)
Patch by Shane H. W. Travis <travis@sedsystems.ca>
r=jake

docs/xml/administration.xml

index 93f7666fb68353fd58c18c907d3566c40eeb9cb1..9384f68a74e7d8ae5a4a562a49e41a6e957ae428 100644 (file)
@@ -5,10 +5,12 @@
   <section id="parameters">
     <title>Bugzilla Configuration</title>
 
-    <para>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.</para>
+    <para>
+      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.
+    </para>
 
     <indexterm>
       <primary>checklist</primary>
     <procedure>
       <step>
         <para> 
-        <command>maintainer</command>:
-        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.</para>
+          <command>maintainer</command>:
+
+          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.
+        </para>
       </step>
 
       <step>
         <para>
-        <command>urlbase</command>:
-        This parameter defines the fully qualified domain name and web 
-        server path to your Bugzilla installation.</para>
-
-        <para>For example, if your Bugzilla query page is
-        <filename>http://www.foo.com/bugzilla/query.cgi</filename>, 
-        set your <quote>urlbase</quote>
-        to <filename>http://www.foo.com/bugzilla/</filename>.</para>
+          <command>urlbase</command>:
+
+          This parameter defines the fully qualified domain name and web 
+          server path to your Bugzilla installation.
+        </para>
+
+        <para>
+          For example, if your Bugzilla query page is
+          <filename>http://www.foo.com/bugzilla/query.cgi</filename>, 
+          set your <quote>urlbase</quote>
+          to <filename>http://www.foo.com/bugzilla/</filename>.
+        </para>
       </step>
 
       <step>
         <para>
-        <command>usebuggroups</command>:
-        This dictates whether or not to implement group-based security for
-        Bugzilla. If set, Bugzilla bugs can have an associated 'group',
-        defining which users are allowed to see and edit the
-        bug.</para>
-
-        <para>Set "usebuggroups" to "on" 
-        <emphasis>only</emphasis>
-        if you may wish to restrict access to particular bugs to certain
-        groups of users. I suggest leaving
-        this parameter <emphasis>off</emphasis>
-        while initially testing your Bugzilla.</para>
-
-        <para>For more information see <xref linkend="groups"/>.</para>
+          <command>usebuggroups</command>:
+
+          This dictates whether or not to implement group-based security for
+          Bugzilla. If set, Bugzilla bugs can have an associated 'group',
+          defining which users are allowed to see and edit the
+          bug.
+        </para>
+
+        <para>
+          Set <quote>usebuggroups</quote> to <quote>on</quote>
+          <emphasis>only</emphasis> if you may wish to restrict access
+          to particular bugs to certain groups of users. I suggest leaving
+          this parameter <emphasis>off</emphasis>
+          while initially testing your Bugzilla.
+        </para>
+
+        <para>
+          For more information see <xref linkend="groups"/>.
+        </para>
       </step>
 
       <step>
         <para>
-        <command>usebuggroupsentry</command>:
-        Bugzilla Products can have a group associated with them, so that
-        certain users can only see bugs in certain products. When this parameter
-        is set to <quote>on</quote>, this places all newly-created bugs in the
-        group for their product immediately.</para>
+          <command>usebuggroupsentry</command>:
+
+          Bugzilla Products can have a group associated with them, so that
+          certain users can only see bugs in certain products. When this
+          parameter is set to <quote>on</quote>, this places all
+          newly-created bugs in the group for their product immediately.
+        </para>
       </step>
 
       <step>
         <para>
-        <command>shadowdb</command>:
-        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. The 
-        <quote>shadowdb</quote>
-        parameter was designed to get around this limitation. While only a
-        single user is allowed to write to a table at a time, reads can
-        continue unimpeded on a read-only shadow copy of the database.
-        Although your database size will double, a shadow database can cause
-        an enormous performance improvement when implemented on extremely
-        high-traffic Bugzilla databases.</para>
+          <command>shadowdb</command>:
+
+          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.
+        </para>
+
+        <para>
+          The <quote>shadowdb</quote> parameter was designed to get around
+          this limitation. While only a single user is allowed to write to
+          a table at a time, reads can continue unimpeded on a read-only
+          shadow copy of the database. Although your database size will
+          double, a shadow database can cause an enormous performance
+          improvement when implemented on extremely high-traffic Bugzilla
+          databases.
+        </para>
         
         <para>
-        As a guide, mozilla.org began needing 
-        <quote>shadowdb</quote>
-        when they reached around 40,000 Bugzilla users with several hundred
-        Bugzilla bug changes and comments per day.</para>
-
-        <para>The value of the parameter defines the name of the 
-        shadow bug database. 
-        Set "shadowdb" to e.g. "bug_shadowdb" if you will be running a
-        *very* large installation of Bugzilla. 
+          As a guide, on reasonably old hardware, mozilla.org began needing 
+          <quote>shadowdb</quote> when they reached around 40,000 Bugzilla
+          users with several hundred Bugzilla bug changes and comments per day.
+        </para>
+
+        <para>
+          The value of the parameter defines the name of the shadow bug
+          database. Set "shadowdb" to e.g. "bug_shadowdb" if you will be
+          running a *very* large installation of Bugzilla.
+        </para>
+
         <note>
-          <para>Enabling "shadowdb" can adversely affect the stability of
-          your installation of Bugzilla. You should regularly check that your
-          database is in sync. It is often advisable to force a shadow
-          database sync nightly via 
-          <quote>cron</quote>.
+          <para>
+            Enabling "shadowdb" can adversely affect the stability of your
+            installation of Bugzilla. You should regularly check that your
+            database is in sync. It is often advisable to force a shadow
+            database sync nightly via <quote>cron</quote>.
           </para>
         </note>
-        </para>
         
-        <para>If you use the "shadowdb" option, it is only natural that you
-        should turn the "queryagainstshadowdb" option on as well. Otherwise
-        you are replicating data into a shadow database for no reason!</para>
-
+        <para>
+          If you use the <quote>shadowdb</quote> option, it is only natural
+          that you should turn the <quote>queryagainstshadowdb</quote>
+          option on as well. Otherwise you are replicating data into a shadow
+          database for no reason!
+        </para>
       </step>
 
       <step>
         <para>
-        <command>shutdownhtml</command>:
+          <command>shutdownhtml</command>:
 
-        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.
-        :-)
+          If you need to shut down Bugzilla to perform administration, enter
+          some descriptive text (with embedded HTML codes, if you'd like)
+          into this box. Anyone who tries to use Bugzilla (including admins)
+          will receive a page displaying this text. Users can neither log in
+          nor log out while shutdownhtml is enabled.
         </para>
+
+        <note>
+          <para>
+            Although regular log-in capability is disabled while 'shutdownhtml'
+            is enabled, safeguards are in place to protect the unfortunate 
+            admin who loses connection to Bugzilla. Should this happen to you,
+            go directly to the <filename>editparams.cgi</filename> (by typing
+            the URL in manually, if necessary). Doing this will prompt you to
+            log in, and your name/password will be accepted here (but nowhere
+            else). 
+          </para>
+        </note>
       </step>
 
       <step>
         <para>
-        <command>passwordmail</command>:
+          <command>passwordmail</command>:
 
-        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.</para>
+          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.
+        </para>
 
-        <para>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.</para>
+        <para>
+          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.
+        </para>
       </step>
 
       <step>
         <para>
-        <command>useqacontact</command>:
+          <command>movebugs</command>:
 
-        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.</para>
+          This option is an undocumented feature to allow moving bugs
+          between separate Bugzilla installations.  You will need to understand
+          the source code in order to use this feature.  Please consult
+          <filename>movebugs.pl</filename> in your Bugzilla source tree for
+          further documentation, such as it is.
+        </para>
       </step>
+
       <step>
         <para>
-        <command>usestatuswhiteboard</command>:
-        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.         
+          <command>useqacontact</command>:
+
+          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.
         </para>
       </step>
 
       <step>
         <para>
-        <command>whinedays</command>:
-        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).</para>
+          <command>usestatuswhiteboard</command>:
+
+          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.         
+        </para>
       </step>
 
       <step>
         <para>
-        <command>commenton*</command>:
-        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.</para>
-
-        <para>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. 
+          <command>whinedays</command>:
+
+          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).
+        </para>
+      </step>
+
+      <step>
+        <para>
+          <command>commenton*</command>:
+
+          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.
+        </para>
+
+        <para>
+          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. 
+        </para>
+
         <note>
-          <para>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!)</para>
+          <para>
+            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!)
+          </para>
         </note>
-        </para>
       </step>
 
       <step>
         <para>
-        <command>supportwatchers</command>:
-
-        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 
-        <quote>watcher</quote>
-        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.</para>        
+          <command>supportwatchers</command>:
+
+          Turning on this option allows users to ask to receive copies 
+          of bug mail sent to another user.  Watching a user with
+          different group permissions is not a way to 'get around' the
+          system; copied emails are still subject to the normal groupset
+          permissions of a bug, and <quote>watchers</quote> will only be 
+          copied on emails from bugs they would normally be allowed to view. 
+        </para>
       </step>
     </procedure>
   </section>