summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/en/xml/administration.xml215
-rw-r--r--docs/en/xml/installation.xml4
2 files changed, 151 insertions, 68 deletions
diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml
index f932beb25..847527203 100644
--- a/docs/en/xml/administration.xml
+++ b/docs/en/xml/administration.xml
@@ -69,8 +69,14 @@
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>
+ 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.
@@ -85,23 +91,10 @@
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.
- <note>
- <para>Enabling "shadowdb" can adversely affect the stability of
- your installation of Bugzilla. You should regularly check that your
- database is in sync. It is often advisable to force a shadow
- database sync nightly via
- <quote>cron</quote>.
- </para>
- </note>
- </para>
-
- <para>If you use the "shadowdb" option, it is only natural that you
- should turn the "queryagainstshadowdb" option on as well. Otherwise
- you are replicating data into a shadow database for no reason!</para>
-
+ shadow bug database. You will need to set the host and port settings
+ from the params page, and set up replication in your database server
+ so that updates reach this readonly mirror. Consult your database
+ documentation for more detail.</para>
</step>
<step>
@@ -129,6 +122,19 @@
blurb about how to use Bugzilla at your site.</para>
</step>
+
+ <step>
+ <para>
+ <command>movebugs</command>:
+
+ This option is an undocumented feature to allow moving bugs
+ between separate Bugzilla installations. You will need to understand
+ the source code in order to use this feature. Please consult
+ <filename>movebugs.pl</filename> in your Bugzilla source tree for
+ further documentation, such as it is.
+ </para>
+ </step>
+
<step>
<para>
<command>useqacontact</command>:
@@ -212,33 +218,11 @@
you for this username and password.</para>
<tip>
- <para>If you wish to add more administrative users, you must use the
- MySQL interface. Run "mysql" from the command line, and use these
- commands:
- <simplelist>
- <member>
- <prompt>mysql&gt;</prompt>
- <command>use bugs;</command>
- </member>
-
- <member>
- <prompt>mysql&gt;</prompt>
-
- <command>
- update profiles set groupset=0x7ffffffffffffff where login_name =
- "(user's login name)";
- </command>
- </member>
- </simplelist>
+ <para>If you wish to add more administrative users, add them to
+ the "admin" group and, optionally, add edit the tweakparams, editusers,
+ creategroups, editcomponents, and editkeywords groups to add the
+ entire admin group to those groups.
</para>
-
- <para>Yes, that is
- <emphasis>fourteen</emphasis>
-
- <quote>f</quote>
-
- 's. A whole lot of f-ing going on if you want to create a new
- administator.</para>
</tip>
</section>
@@ -698,10 +682,22 @@
</listitem>
<listitem>
- <para>Fill out the "New Name", "New Description", and
- "New User RegExp" fields. "New User RegExp" allows you to automatically
+ <para>Fill out the "Group", "Description", and
+ "User RegExp" fields. "New User RegExp" allows you to automatically
place all users who fulfill the Regular Expression into the new group.
When you have finished, click "Add".</para>
+ <warning>
+ <para>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.</para>
+ </warning>
+ </listitem>
+ <listitem>
+ <para>After you add your new group, edit the new group. On the
+ edit page, you can specify other groups that should be included
+ in this group and which groups should be permitted to add and delete
+ users from this group.</para>
</listitem>
</orderedlist>
@@ -712,17 +708,6 @@
<para>Turn on "usebuggroups" and "usebuggroupsentry" in the "Edit
Parameters" screen.</para>
- <warning>
- <para>XXX is this still true?
- "usebuggroupsentry" has the capacity to prevent the
- administrative user from directly altering bugs because of
- conflicting group permissions. If you plan on using
- "usebuggroupsentry", you should plan on restricting
- administrative account usage to administrative duties only. In
- other words, manage bugs with an unpriveleged user account, and
- manage users, groups, Products, etc. with the administrative
- account.</para>
- </warning>
</listitem>
<listitem>
@@ -734,13 +719,6 @@
</listitem>
</orderedlist>
- <warning>
- <para>Bugzilla currently has a limit of 64 groups per installation. If
- you have more than about 50 products, you should consider
- running multiple Bugzillas. Ask in the newsgroup for other
- suggestions for working around this restriction.</para>
- </warning>
-
<para>
Note that group permissions are such that you need to be a member
of <emphasis>all</emphasis> the groups a bug is in, for whatever
@@ -1128,6 +1106,19 @@
By modifying this, you can tell your users how they should report
bugs.
</para>
+
+ <para>
+ <command>bug/process/midair.html.tmpl</command>:
+ 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.
+ </para>
<para>
<command>bug/create/create.html.tmpl</command> and
@@ -1176,6 +1167,100 @@
</section>
+ <section id="cust-change-permissions">
+ <title>Change Permission Customisation</title>
+
+ <warning>
+ <para>
+ This feature should be considered experimental; the Bugzilla code you
+ will be changing is not stable, and could change or move between
+ versions. Be aware that if you make modifications to it, you may have
+ to re-make them or port them if Bugzilla changes internally between
+ versions.
+ </para>
+ </warning>
+
+ <para>
+ Companies often have rules about which employees, or classes of employees,
+ are allowed to change certain things in the bug system. For example,
+ only the bug's designated QA Contact may be allowed to VERIFY the bug.
+ Bugzilla has been
+ designed to make it easy for you to write your own custom rules to define
+ who is allowed to make what sorts of value transition.
+ </para>
+
+ <para>
+ For maximum flexibility, customising this means editing Bugzilla's Perl
+ code. This gives the administrator complete control over exactly who is
+ allowed to do what. The relevant function is called
+ <filename>CheckCanChangeField()</filename>,
+ and is found in <filename>process_bug.cgi</filename> in your
+ Bugzilla directory. If you open that file and grep for
+ "sub CheckCanChangeField", you'll find it.
+ </para>
+
+ <para>
+ This function has been carefully commented to allow you to see exactly
+ how it works, and give you an idea of how to make changes to it. Certain
+ marked sections should not be changed - these are the "plumbing" which
+ makes the rest of the function work. In between those sections, you'll
+ find snippets of code like:
+ <programlisting> # Allow the owner to change anything.
+ if ($ownerid eq $whoid) {
+ return 1;
+ }</programlisting>
+ It's fairly obvious what this piece of code does.
+ </para>
+
+ <para>
+ So, how does one go about changing this function? Well, simple changes
+ can be made just be removing pieces - for example, if you wanted to
+ prevent any user adding a comment to a bug, just remove the lines marked
+ "Allow anyone to change comments." And if you want the reporter to have
+ no special rights on bugs they have filed, just remove the entire section
+ which refers to him.
+ </para>
+
+ <para>
+ More complex customisations are not much harder. Basically, you add
+ a check in the right place in the function, i.e. after all the variables
+ you are using have been set up. So, don't look at $ownerid before
+ $ownerid has been obtained from the database. You can either add a
+ positive check, which returns 1 (allow) if certain conditions are true,
+ or a negative check, which returns 0 (deny.) E.g.:
+ <programlisting> if ($field eq "qacontact") {
+ if (UserInGroup("quality_assurance")) {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }</programlisting>
+ This says that only users in the group "quality_assurance" can change
+ the QA Contact field of a bug. Getting more weird:
+ <programlisting> if (($field eq "priority") &&
+ ($vars->{'user'}{'login'} =~ /.*\@example\.com$/))
+ {
+ if ($oldvalue eq "P1") {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }</programlisting>
+ This says that if the user is trying to change the priority field,
+ and their email address is @example.com, they can only do so if the
+ old value of the field was "P1". Not very useful, but illustrative.
+ </para>
+
+ <para>
+ For a list of possible field names, look in
+ <filename>data/versioncache</filename> for the list called
+ <filename>@::log_columns</filename>. If you need help writing custom
+ rules for your organisation, ask in the newsgroup.
+ </para>
+ </section>
+
<section id="upgrading">
<title>Upgrading to New Releases</title>
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml
index 8d1a94ec7..7aec021ce 100644
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
@@ -559,9 +559,7 @@ AllowOverride Limit
<para>There are important files and directories that should not be a
served by the HTTP server - most files in the
<quote>data</quote>
- and
- <quote>shadow</quote>
- directories and the
+ directory and the
<quote>localconfig</quote>
file. You should configure your HTTP server to not serve
these files. Failure to do so will expose critical passwords and