source: trunk/doc/src/docbook/admindoc/user_administration.xml @ 5683

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: user_administration.xml 5683 2011-08-02 08:32:20Z nicklas $

  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Martin Svensson

  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/

  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.

  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<chapter id="user_administration">
  <?dbhtml dir="user_administration"?>
  <title>Account administration</title>

  <important>
    <title>Read <link linkend="project_permission"><xref linkend="project_permission" /></link></title>
    <para>
      This chapter contains important information about the
      permission system BASE uses. It is essential that an 
      administrator knows how this works to be able to set up
      user, groups and roles smoothly.
    </para>
  </important>

  <sect1 id="user_administration.users">
    <title>Users administration</title>
    <para>
      The user list is accessed with
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guimenuitem>Users</guimenuitem>
      </menuchoice>
      and from here are the users' account and contact information managed.
    </para>

    <sect2 id="user_administration.users.edit">
      <title>Edit user</title>
      <para>
        The pop-up window where information and settings for a user can be edited has three
        tabs, one for the account related, one with information about the user and one that
        shows the user's memberships.
      </para>
      <sect3 id="user_administration.users.edit.properties">        
        <title>Properties</title>
        <helptext external_id="user.edit" title="Edit user account">
          <para>These are the properties for a user account.</para>
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Name</guilabel>
              </term>
              <listitem>
                <para>
                  The full name of the user that is associated with the account.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Login</guilabel>
              </term>
              <listitem>
                <para>
                  A login name to use when logging in to the account. The login
                  must be unique among all users.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>External ID</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  An id that is used to identify the user outside BASE (optional).
                  If a value is given it must be unique among all users.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>New password</guilabel>
              </term>
              <listitem>
                <para>
                  This is used together with the login name to log in to the
                  account. This is a required field for a new user or if the
                  password should be changed. If the field is left empty the
                  password will be unchanged
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Retype password</guilabel>
              </term>
              <listitem>
                <para>
                  Retype the password that is written in
                  <guilabel>New password</guilabel>.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Quota</guilabel>
                </optional>
              </term>
              <listitem>
                <para>Set disk quota for the account.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Quota group</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  Set this if the account should belong to a group with specified
                  quota (optional). With this set the user's possibilities to save items to
                  disk will also depend on how much the rest of the group has
                  saved.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Home directory</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  Set the account's home directory (optional). A new directory, either empty
                  or from a template, can be created if editing a new user. Select
                  <guilabel>- none -</guilabel>
                  if there should not be any home directory associated with the
                  account.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Expiration date</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  Define a date in this field if the account should expire on a
                  certain day (optional). The account will be disabled after this date.
                  Leave this empty if the account never should expire.
                  <tip>
                    <para>
                      Use the
                      <guibutton>Calendar&hellip;</guibutton>
                      button to pick a date from a calendar in a pop-up window.
                    </para>
                  </tip>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Multi-user account</guilabel>
              </term>
              <listitem>
                <para>
                  This checkbox should be checked if the account should be used by
                  more one user. This will prevent the users from changing the
                  password, contact information and other settings. It will
                  also reset all list filters, column configurations, etc. 
                  when the user logs out. Normally, these settings are remembered
                  between log ins.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Disabled</guilabel>
              </term>
              <listitem>
                <para>
                  Disable the account.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          <para>
            Go to the other tabs if there are any changes to do otherwise press
            &gbSave;
            to save the values or
            &gbCancel;
            to abort.
          </para>
          <seeother>
            <other external_id="user.edit.contact">Edit contact information</other>
            <other external_id="user.additional">Edit additional info</other>
            <other external_id="user.edit.membership">Group and role membership</other>
          </seeother>
        </helptext>
      </sect3>

      <sect3 id="user._administration.users.edit.contact">
        <title>Contact information</title>
        <helptext external_id="user.edit.contact" title="Edit user's contact information">
          <para>
            Information about how to get in contact with the user that is associated
            with the account. All fields on this tab are optional and do not necessarily
            need to have a value but some can be good to set, like email or phone
            number.
          </para>
          <variablelist>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Email</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  User's email address. There is some verification of the value
                  but there is no check if the email really exists.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Organization</guilabel>
                </optional>
              </term>
              <listitem>
                <para>The company or organization that the user works for.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Address</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  User's mail address. Use the magnifying glass down to the right,
                  to edit this property in a larger window.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Phone</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  User's phone number(s)
                  <note>
                    <para>
                      There is no special field for mobile phone, but it works
                      fine to put more then one number in this field.
                    </para>
                  </note>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Fax</guilabel>
                </optional>
              </term>
              <listitem>
                <para>User's fax number.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Url</guilabel>
                </optional>
              </term>
              <listitem>
                <para>A URL that is associated with the user.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Description</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  Other useful contact information or description about the user
                  can be written in this field. Use the magnifying glass to edit
                  the information in a pop-up window with a larger text-area.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          <para>
            Go to the other tabs if there are any changes to do otherwise press
            &gbSave;
            to save the values or
            &gbCancel;
            to abort.
          </para>
          <seeother>
            <other external_id="user.edit">Edit account</other>
            <other external_id="user.additional">Edit additional info</other>
            <other external_id="user.edit.membership">Group and role membership</other>
          </seeother>
        </helptext>
      </sect3>

      <sect3 id="user_administration.users.edit.additional">
        <title>Additional information</title>
        <helptext external_id="user.edit.additional" title="Additional information">
          <para>
            This tab contains fields that hold various information about the user. There are
            by default two fields in BASE but this could easily be changed by the
            server administrator. How this configuration is done can be read in
            <xref linkend="appendix.extendedproperties" />
            <note>
              <para>
                The
                <guilabel>Additional info</guilabel>
                tab is only visible if there is one or more property defined for
                <classname docapi="net.sf.basedb.core.data">UserData</classname>
                in the configuration file for extended properties.
              </para>
            </note>
            
            These are the fields that are installed with BASE
            <variablelist>
              <varlistentry>
                <term>
                  <guilabel>Mobile</guilabel>
                </term>
                <listitem>
                  <para>
                    The user's mobile number could be put in this field. This
                    field could be left empty.
                  </para>
                </listitem>
              </varlistentry>
              <varlistentry>
                <term>
                  <guilabel>Skype</guilabel>
                </term>
                <listitem>
                  <para>
                    Skype contact information, if the user has a registered
                    Skype account. This field could be left empty.
                  </para>
                </listitem>
              </varlistentry>
            </variablelist>
          </para>
          <para>
            Go to the other tabs if there are any changes to do otherwise press
            &gbSave;
            to save the values or
            &gbCancel;
            to abort.
          </para>
          <seeother>
            <other external_id="user.edit">Edit account</other>
            <other external_id="user.contact">Edit contact</other>
            <other external_id="user.edit.membership">Group and role membership</other>
          </seeother>
        </helptext>
      </sect3>

      <sect3 id="user_administration.users.edit.membership">
        <title>Group and role membership</title>
        <helptext external_id="user.edit.membership" title="Group and role membership">
          <para>
            On this tab, the group and role membership of a user can be
            specified. The membership can also be changed by editing the
            group and/or role.
            
            <note>
              <para>
              When adding a new user, the user is automatically added
              as a member to all groups and roles that has been marked
              as <emphasis>default</emphasis>. In the standard BASE distribution
              the <emphasis>User</emphasis> role is marked as a default role.
              </para>
            </note>
          </para>
          
          <variablelist>
            <varlistentry>
              <term><guilabel>Member in</guilabel></term>
              <listitem>
                <para>
                Lists the groups and roles the user already is a member of.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guilabel>Add groups&hellip;</guilabel></term>
              <listitem>
                <para>
                Opens a pop-up window that allows you to select
                groups. In the pop-up window, mark
                one or more groups and click on the &gbOk;
                button. The pop-up window will not list groups that 
                the user already is a member of.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guilabel>Add roles&hellip;</guilabel></term>
              <listitem>
                <para>
                Opens a pop-up window that allows you to select
                roles. In the pop-up window, mark
                one or more roles and click on the &gbOk;
                button. The pop-up window will not list roles that 
                the user already is a member of.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guilabel>Remove</guilabel></term>
              <listitem>
                <para>
                Use this button to remove the user from the selected
                groups and/or roles. The selected items will then disappear 
                from the list of memberships.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          
          <para>
            Go to the other tabs if there are any changes to do otherwise press
            &gbSave;
            to save the values or
            &gbCancel;
            to abort.
          </para>
          <seeother>
            <other external_id="user.edit">Edit user</other>
            <other external_id="user.edit.contact">Edit contact information</other>
            <other external_id="user.additional">Edit additional info</other>
            <other external_id="user.edit.default_membership">Default group and role membership</other>
          </seeother>
        </helptext>
      </sect3>
    </sect2>
    
    <sect2 id="user_administration.users.default_membership">
      <title>Default group and role membership</title>
      
      <helptext external_id="user.edit.default_membership" 
        title="Default group and role membership">
        <para>
          It is possible to automatically let BASE add new users
          as a member of a pre-defined list of groups and/or roles. This is done
          by marking those groups and roles as <emphasis>default</emphasis>
          groups and roles. There are two ways to do this.
        </para>
        
        <orderedlist>
        <listitem>
          <para>
          Change the flag in the edit-dialog for each of the groups/roles
          that you want to assign as default.
          </para> 
        </listitem>
        
        <listitem>
          <para>
          Use the <guibutton>Default membership</guibutton> button on the
          <menuchoice>
            <guimenu>Administrate</guimenu>
            <guimenuitem>Users</guimenuitem>
          </menuchoice>
          page and select groups and roles in a pop-up dialog.
          The dialog lists all groups and roles that are currently
          assigned as default. Use the <guibutton>Add groups</guibutton>
          and <guibutton>Add roles</guibutton> buttons to select more
          groups and roles. Use the <guibutton>Remove</guibutton> button
          to remove the selected groups/roles.
          </para>
        </listitem>
        </orderedlist>
        
        <note>
          <para>
          Changing which groups and roles that are the default does not affect
          existing user accounts. They are only used to assign membership to
          new users.
          </para>
        </note>
        <seeother>
          <other external_id="user.edit.membership">Edit user group and role membership</other>
        </seeother>
      </helptext>
    </sect2>
  </sect1>

  <sect1 id="user_administration.groups">
    <title>Groups administration</title>
    <para>
      Groups in BASE are meant to represent the organizational structure of
      a company or institution. For example, there can be one group for each 
      department and subgroups for the teams in the departments.
      The group-membership is normally set when the user is added to BASE and
      should not have to be changed later, except when the company is re-organizing.
    </para>
    <para>
      There is one pre-installed group in BASE, a system group, called Everyone. It is, like
      the name says, a group in which everyone (all users) are members. The users that are
      allowed to share to everyone can easily share items to all users by sharing the item to
      this group.
    </para>

    <sect2 id="user_administration.groups.edit">
      <title>Edit group</title>
      <para>
        The pop-up window where a group can be edited has two tabs,
        <guilabel>Group</guilabel>
        and
        <guilabel>Members</guilabel>.
      </para>
      <sect3 id="user_administration.groups.edit.properties">
        <title>Properties</title>
        <helptext external_id="group.edit" title="Edit group">
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Name</guilabel>
              </term>
              <listitem>
                <para>The name of the group.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Default</guilabel>
              </term>
              <listitem>
                <para>
                  Mark this checkbox to let BASE automatically add new users
                  as members to this group.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Hidden members</guilabel>
              </term>
              <listitem>
                <para>
                  Mark this checkbox to create a group with hidden members. 
                  This means that a user will not be able to see information about
                  other members in the group, but it is still possible to share items
                  to the group as a whole.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Description</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  Description about the group. The magnifying glass, down to the
                  right, can be used to open and edit the text in a larger text
                  area.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Quota</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  With this property it's possible to limit the quota of total
                  disk space for the group members. Select
                  <guilabel>-none-</guilabel>
                  from the drop-down list if the group should not have any quota.
                  There are some presets of quotas that comes with the BASE
                  installation, besides a couple with different size of total disk
                  space there are one called
                  <guilabel>No quota</guilabel>
                  and one with
                  <guilabel>Unlimited quota</guilabel>.
                  Their names speak for them self.
                </para>
                
                <note>
                  <para>
                  A user can only take quota from one group, which has
                  to be specified as the <guilabel>Quota group</guilabel>
                  of the user.
                  </para>
                </note>
                
              </listitem>
            </varlistentry>
          </variablelist>
          <para>
            Go to the other tab,
            <guilabel>Members</guilabel>,
            if there are any changes to do otherwise use
            &gbSave;
            to save the settings or
            &gbCancel;
            to abort.
          </para>
          <seeother>
            <other external_id="group.edit.membership">Edit group members</other>
            <other external_id="user.edit">Edit user</other>
          </seeother>
        </helptext>
      </sect3>

      <sect3 id="user_administration.groups.edit.members">
        <title>Group members</title>
        <helptext external_id="group.edit.membership" title="Edit group members">
          <para>
            A group can have both single users and other groups as members. Group
            members have access to those items that are shared to the group. Each user
            in the group has the possibility to share their own items to one or more of
            the other members or to the whole group.
          </para>
          
          <variablelist>
            <varlistentry>
              <term><guilabel>Members</guilabel></term>
              <listitem>
                <para>
                  Lists the user and groups that are already
                  members of this group.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guilabel>Add users&hellip;</guilabel></term>
              <listitem>
                <para>
                Opens a pop-up window that allows you to add
                users to the group. In the pop-up window, mark
                one or more users and click on the &gbOk;
                button. The pop-up window will not list users that 
                are already members of the group.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guilabel>Add groups&hellip;</guilabel></term>
              <listitem>
                <para>
                Opens a pop-up window that allows you to add
                other groups to the group. In the pop-up window, mark
                one or more groups and click on the &gbOk;
                button. The pop-up window will not list groups that 
                are already members of the group.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guilabel>Remove</guilabel></term>
              <listitem>
                <para>
                Use this button to remove the selected
                users and/or groups from this group. The selected items will 
                disappear from the list of memberships.
                </para>
              </listitem>
            </varlistentry>
            
          </variablelist>
          
          <para>
            Go to the other tab if there are any changes to do, otherwise use
            &gbSave;
            to save the values or
            &gbCancel;
            to abort.
          </para>
          <seeother>
            <other external_id="group.edit">Edit group properties</other>
          </seeother>
        </helptext>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="user_administration.roles">
    <title>Roles administration</title>
    <para>
      Roles are meant to represent different kinds of working positions that users can have, 
      like server administrator or regular user just to mention two.
      Users are normally assigned a role, perhaps more than one, when they are created and
      registered in BASE.
    </para>


    <sect2 id="user_administration.roles.defaultroles">
      <title>Pre-defined system roles</title>
      <para>
        BASE comes with some pre-defined roles. These are configured to cover the
        normal user roles that can appear. A more detailed description of the different
        roles and when to use them follows here.
      </para>
      <variablelist>
        <varlistentry>
          <term>Administrator</term>
          <listitem>
            <para>
              This role gives the user full permission to do everything in BASE and
              also possibility to share items with the system-group 'Everyone'. Users
              that are supposed to administrate the server, user accounts, groups etc.
              should have this role.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Supervisor</term>
          <listitem>
            <para>
              Users that are members of this role has permission to read everything in
              BASE. This role does not let the members to actually do anything in BASE
              except read and supervise.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Power user</term>
          <listitem>
            <para>
              This role allows it's members to do some things that an ordinary user
              not is allowed to. Most things are related to global resources
              like reporters, the array lims and plug-ins.
              This role can be proper for those users that are in
              some kind of leading position over work groups or projects.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>User</term>
          <listitem>
            <para>
              A role that is suitable for all ordinary users. This allows the members
              to do common things in BASE such as creating biomaterials and
              experiments, uploading raw data and analyse it.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Guest</term>
          <listitem>
            <para>
              This is a role with limited access to create new things. It is useful
              for those who wants to have peek at the program. It can also be
              used for someone that is helping out with the analysis of an experiment.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Job agent</term>
          <listitem>
            <para>
              This role is given to the job agents and allows them to read and execute
              jobs. Job agents always runs the jobs as the user who created the job
              and therefore it have to be able to act as another user.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="user_administration.roles.edit">
      <title>Edit role</title>
      <para>
        Creating a new role or editing the system-roles are something that do not needs to be
        done very often. The existing roles will normally be enough but there can be some
        cases when they need to be complemented, either with a new role or with different
        permissions.
      </para>
      <sect3 id="user_administration.roles.edit.properties">
        <title>Properties</title>
        <helptext external_id="role.edit" title="Edit role">

          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Name</guilabel>
              </term>
              <listitem>
                <para>The name of the role.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Share to Everyone</guilabel>
              </term>
              <listitem>
                <para>
                Allows the user to share items to the 
                system-group 'Everyone'.
                </para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><guilabel>Act as another user</guilabel></term>
              <listitem>
                <para>
                  Allows the user to login as another user without
                  knowing the password. This is used by job agents
                  to make it possible for them to execute a plug-in
                  as the user that created the job. This permission
                  will also make it possible to switch user in the web
                  interface. It can be useful for an administrator who
                  needs to check out a problem, but use this permission
                  with care.
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>
                <guilabel>Select job agent for jobs</guilabel>
              </term>
              <listitem>
                <para>
                Allows the user to select a specific job agent when running jobs.
                Users without this permission will always have a randomly selected
                job agent.
                </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>
                <guilabel>Default</guilabel>
              </term>
              <listitem>
                <para>
                  Mark this checkbox to let BASE automatically add new users
                  as members to the role.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Description</guilabel>
              </term>
              <listitem>
                <para>Description and information about the role.</para>
              </listitem>
            </varlistentry>
          </variablelist>
          <para>
            Set the properties and proceed then to either one of the other tabs or by
            clicking on one of the buttons:
            &gbSave;
            to save the changes or
            &gbCancel;
            to abort.
          </para>
          <seeother>
            <other external_id="role.edit.permissions">Role permissions</other>
            <other external_id="role.edit.members">Role members</other>
          </seeother>
        </helptext>
      </sect3>

      <sect3 id="user_administration.roles.edit.permissions">
        <title>Permissions</title>
        <helptext external_id="role.edit.permissions" title="Edit role permissions">
          <para>
            A role's permissions are defined for each item type within BASE. Set the
            role's permission on an item type by first selecting the item(s) in the list
            and then tick those permissions that should be applied. Not all permissions
            can be applied to every item type, that's why permission check-boxes becomes
            disabled when selecting some of the item types
          </para>
          <para>
            After each item type in the list is a string inside square brackets that
            shows what kind of permissions the current role has on that particular item
            type. The permissions that do not have been set are represented with '-'
            inside the square brackets and those which have been set are represented
            with characters that are listed below.
          </para>
          <itemizedlist>
            <listitem>
              <simpara>
                <guilabel>DENIED</guilabel>
                = Deny access to the selected item type. This exclude all the other
                permissions by unchecking the other check boxes.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <guilabel>C</guilabel>
                = Create
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <guilabel>R</guilabel>
                = Read
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <guilabel>U</guilabel>
                = Use
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <guilabel>W</guilabel>
                = Write
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <guilabel>D</guilabel>
                = Delete
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <guilabel>O</guilabel>
                = Set owner
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <guilabel>P</guilabel>
                = Set permission
              </simpara>
            </listitem>
          </itemizedlist>
          <para>
            Set the role's permission on each one of the item types and proceed then to
            one of the other tabs or click on 
            &gbSave;
            to save the changes or
            &gbCancel;
            to abort.
          </para>
          <seeother>
            <other external_id="role.edit">Edit properties</other>
            <other external_id="role.edit.members">Role members</other>
          </seeother>
        </helptext>
      </sect3>

      <sect3 id="user_administration.roles.edit.members">
        <title>Members</title>
        <helptext external_id="role.edit.members" title="Role members">
        
        <variablelist>
          <varlistentry>
            <term><guilabel>Members</guilabel></term>
            <listitem>
              <para>
              Users that are members of a role are listed in the list-box located on this
              tab.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><guibutton>Add users</guibutton></term>
            <listitem>
              <para>
                Select the users that should be added from the list in the
                pop-up window. Click on the
                &gbOk;
                button to close the pop-up window and add the selected users.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
              <term>Remove</term>
              <listitem>
                <para>
                  Removes the selected users from the role.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          <para>
            Press
            &gbSave;
            to save the role or go to one of the other tabs if there are more that needs
            to be set. Use
            &gbClose;
            to abort and close the window without saving the changes.
          </para>
          <seeother>
            <other external_id="role.edit">Edit properties</other>
            <other external_id="role.edit.permissions">Role permissions</other>
          </seeother>
        </helptext>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="user_administration.quota">
    <title>Disk space/quota</title>
    <para>
      The administrator can control the maximum size of disk space for users and groups.
      A user must be assigned a quota of their own and may optionally have a group
      quota as well. If so, the most restrictive quota is checked whenever the user
      tries to do something that counts as disk-consuming, for example uploading a file.
    </para>
    
    <note>
      <para>
      The quota is checked before an operation, which is allowed to continue if there
      is space left. For example, even if you have only one byte left of disk space
      you are allowed to upload a 10MB file.
      </para>
    </note>
      
    <para>
      Read
      <xref linkend="user_administration.users.edit" />
      and <xref linkend="user_administration.groups.edit" />
      for information about how to set a quota for a user and 
      group.
    </para>
    <para>
      The list of quotas in BASE can be found by using the menu
      <menuchoice>
        <guimenu>Administrate</guimenu>
        <guimenuitem>Quota</guimenuitem>
      </menuchoice>.
    </para>

    <sect2 id="user_administration.quota.edit">
      <title>Edit quota</title>
      <para>
        The edit window has two tabs, one with information about the quota and one where the
        limits are defined.
      </para>
      <sect3 id="user_administration.quota.edit.properties">
        <title>Properties</title>
        <helptext external_id="quota.edit" title="Edit properties">
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Name</guilabel>
              </term>
              <listitem>
                <para>Name of the quota.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Description</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  Description of the quota. It could be a good idea to
                  describe the quota's details here. Use the magnifying glass to
                  edit the text in a larger text area.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          <para>
            Go to the other tab if there are values that have not been set. Otherwise use
            &gbSave;
            to save the settings or
            &gbCancel;
            to abort.
          </para>
        </helptext>
      </sect3>

      <sect3 id="user_administration.quota.edit.values">
        <title>Values</title>
        <helptext external_id="quota.edit.values" title="Edit quota values">
          <para>
            The quota values are defined here, both for the primary location and the
            secondary location. Use the check box to the right of the input fields to
            set unlimited quota. You can use the abbreviations 
            <abbrev>kb</abbrev>, <abbrev>Mb</abbrev> and <abbrev>Gb</abbrev>
            to specify the quota values.
          </para>
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Total</guilabel>
              </term>
              <listitem>
                <para>
                  Limit of total quota. The sum of the other three quotas does not
                  have to be the same as this, it is always the most restricted
                  value that is used.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Files</guilabel>
                </optional>
              </term>
              <listitem>
                <para>Limit of disk space to save files in.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Raw data</guilabel>
                </optional>
              </term>
              <listitem>
                <para>Limit of disk space to save raw data in.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Experiments</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  Limit of disk space that can be used by experiments.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          <para>
            When everything have been set the quota is saved by using
            &gbSave;. To discard changes use
            &gbCancel;.
          </para>
        </helptext>
      </sect3>
    </sect2>
    
    <sect2 id="user_administration.quota.diskusage">
      <title>Disk usage</title>
      
      <para>
        Go to 
        <menuchoice>
          <guimenu>Administrate</guimenu>
          <guimenuitem>Disk usage</guimenuitem>
        </menuchoice>
        if you want to get statistics about how the disk
        is used. There are three tabs:
      </para>
      
      <variablelist>
        <varlistentry>
          <term><guilabel>Overview</guilabel></term>
          <listitem>
            <para>
              Gives an overview of the total disk usage.
              It is divided per location and quota type.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Per user</guilabel></term>
          <listitem>
            <para>
              Gives an overview of the disk usage
              per user. For each user you can get a summary
              displaying the total disk usage and 
              divided per location and quota type. 
              Use the <guilabel>View details</guilabel>
              link to list all items that uses up disk space.
              The list displays the name and type of each item
              and the amount of disk space it uses.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><guilabel>Per group</guilabel></term>
          <listitem>
            <para>
              Gives an overview of the disk usage
              per group, with the same functionality
              as the per user overview.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
      
    </sect2>
    
  </sect1>
</chapter>