diff options
| -rw-r--r-- | docs/en/xml/administration.xml | 215 | ||||
| -rw-r--r-- | docs/en/xml/installation.xml | 4 |
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></prompt> - <command>use bugs;</command> - </member> - - <member> - <prompt>mysql></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 |