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

<?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 3300 2007-05-07 15:08:27Z martin $

  Copyright (C) Authors contributing to this file.

  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 2
  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 this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->

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

  <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 users' account and contact information managed.
    </para>

    <sect2 id="user_administration.users.edit">
      <title>Edit user</title>      

      <helptext external_id="user.edit" title="Edit user account">
        <sect3 id="user_administration.users.edit.properties">
          <title>Properties</title>
          <para>
            These are the properties for an user account.
          </para>
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Name</guilabel>
              </term>
              <listitem>
                <para>
                  The full name of the user that is associated with this account.
                  (Required)
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Login</guilabel>
              </term>
              <listitem>
                <para>
                  A login name to use when logging in to this account. (Required)
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>External ID</guilabel>
                </optional>
              </term>
              <listitem>
                <para>Id used identify the user outside BASE. (Optional)</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>New password</guilabel>
              </term>
              <listitem>
                <para>
                  This is used together with the login name to log in with this
                  account. This is required for a new user or if the password
                  should be changed.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Retype password</guilabel>
              </term>
              <listitem>
                <para>
                  Retype the password in <guilabel>New password</guilabel>.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Quota</guilabel>
                </optional>
              </term>
              <listitem>
                <para>Set disk quota for this account.(Required)</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)
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Home directory</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  Set the account's home directory. A new directory, either empty
                  or from a template, can be created if editing a new
                  user.(Optional)
                </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. The account will be disabled after this
                  date.(Optional)
                  <tip>
                    <para>
                      Use
                      <guibutton>Calendar&hellip;</guibutton>
                      to pick a date from a calendar-pop-up window.
                    </para>
                  </tip>
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Multi-user account</guilabel>
              </term>
              <listitem>
                <para>
                  This checkbox should be ticked if the account should be used by
                  more one user. It will block the users of the account to change
                  password, contact information and other personal information.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Disabled</guilabel>
              </term>
              <listitem>
                <para>
                  Disable the account to be used.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>
        <para>
          Go to the other tabs if there are any changes to do otherwise press
          <guibutton>Save</guibutton>
          to save the values or
          <guibutton>Cancel</guibutton>
          to abort.
        </para>
        <seeother>
          <other external_id="user.edit.contact">Edit user's contact information</other>
          <other external_id="user.edit.membership">Edit user's membership</other>
        </seeother>
      </helptext>
      <helptext external_id="user.edit.contact" title="Edit user's contact information">
        <sect3 id="user._administration.users.edit.contact">
          <title>Contact information</title>
          <para>
            Information how get in contact with the user that is connected to the
            account. All fields on this tab are optional and do not necessarily need to
            have a value.
          </para>
          <variablelist>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Email</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  User's email address.There is some verification of the value but
                  their is no check if the email really exists.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Organisation</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  The company or organisation that the user works for.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Address</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  User's address. Use the magnifying glas down to the right, to
                  edit this property in a larger window - opened in a pop-up
                  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>Fill in any URL associated with the user here.</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Description</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  Other useful contact information or description about the user should 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>
        </sect3>
        <para>
          Go to the other tabs if there are any changes to do otherwise press
          <guibutton>Save</guibutton>
          to save the values or
          <guibutton>Cancel</guibutton>
          to abort.
        </para>
        <seeother>
          <other external_id="user.edit">Edit account</other>
          <other external_id="user.edit.membership">Edit user's membership</other>
        </seeother>
      </helptext>

      <helptext external_id="user.edit.membership" title="Edit user's membership">
        <sect3 id="user_administration.users.edit.membership">
          <title>User's membership</title>
          <para>
            An user's membership in groups and roles can be set on this tab. The
            membership can also be changed by adding/removing the user to/from a
            group's/role's list of members that is described in
            <link linkend="user_administration.groups.edit">edit group</link>
            and
            <link linkend="user_administration.roles.edit">edit role</link>
          </para>
          <para>
            Use
            <guibutton>Add groups&hellip;</guibutton>
            or
            <guibutton>Add roles&hellip;</guibutton>
            to add a membership in a group or a role. Mark the checkboxes for those
            groups or roles that the user should become a member in.
          </para>
          <para>
            Use
            <guibutton>Remove</guibutton>
            to delete membership(s) from selected groups and roles in the list. The
            selected items will then disappear from the list of memberships.
          </para>
        </sect3>
        <para>
          Go to the other tabs if there are any changes to do otherwise press
          <guibutton>Save</guibutton>
          to save the values or
          <guibutton>Cancel</guibutton>
          to abort.
        </para>
        <seeother>
          <other external_id="user.edit">Edit account</other>
          <other external_id="user.edit.contact">Edit user's contact information</other>
        </seeother>
      </helptext>
    </sect2>
  </sect1>

  <sect1 id="user_administration.groups">
    <title>Groups administration</title>
    <para></para>

    <sect2 id="user_administration.groups.edit">
      <title>Edit group</title>
      <para></para>
      <helptext external_id="group.edit" title="Edit group">
        <sect3 id="user_administration.groups.edit.properties">
          <title>Properties</title>
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Name</guilabel>
              </term>
              <listitem>
                <para>Group's name.(Required)</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <optional>
                  <guilabel>Description</guilabel>
                </optional>
              </term>
              <listitem>
                <para>
                  Description about the group. The magifying glass, down to the
                  right, can be used to open 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 dropdown list if the group shouldn't be a quota group.
                  There are some presets of quotas that comes with the BASE2
                  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>
                  . The names speak for them self.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
        </sect3>
        <para>
          Go to the other tab,
          <guilabel>Members</guilabel>
          , if there are any changes to do otherwise press
          <guibutton>Save</guibutton>
          to save the values or
          <guibutton>Cancel</guibutton>
          to abort.
        </para>
        <seeother>
          <other external_id="group.edit.membership">Edit group members</other>
        </seeother>
      </helptext>
      
      <helptext external_id="group.edit.membership" title="Edit group members">
        <sect3 id="user_administration.groups.edit.members">
          <title>Group members</title>
          <para>
            A group can have both single users and whole groups as members. Group
            members have access to those items that are shared to the group. Each user
            in the group can choose to share their own items to one or more of the other
            members or to the whole group.
          </para>
          <para>
            The listbox shows the group's members, both users and other groups.

            Removing members from a group are done by first select one or several
            members in the list and then click on
            <guibutton>Remove</guibutton>
            . The selected items will then disappear from the list.
          </para>
        </sect3>
        <para>
          Go to the group tab if there are any changes to do, otherwise press
          <guibutton>Save</guibutton>
          to save the values or
          <guibutton>Cancel</guibutton>
          to abort.
        </para>
        <seeother>
          <other external_id="group.edit">Edit group properties</other>
        </seeother>
      </helptext>
    </sect2>

  </sect1>

  <sect1 id="user_administration.roles">
    <title>Roles administration</title>
    <para></para>
    <sect2 id="user_administration.roles.defaultroles">
      <title>Default roles</title>
      <para>
        There some default roles that come with BASE2. 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 everything in BASE and also
              possibility to share items with the system-group 'Everyone'. Users that
              are supposed to administrate the server, users 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 doesn't let the members to actually do anything in BASE
              except read.
            </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. This role can be proper for those users that are in
              some kind of leading position over workgroups or projects.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>User</term>
          <listitem>
            <para>
              Role for regular users to have. This allows the members to do common
              things in BASE as analysis, creating biomaterials and experiments and so
              on.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </sect2>

    <sect2 id="user_administration.roles.edit">
      <title>Edit role</title>
      <para></para>
      <helptext external_id="role.edit" title="Edit role">
        <sect3 id="user_administration.roles.edit.properties">
          <title>Properties</title>
          <para></para>
          <variablelist>
            <varlistentry>
              <term>
                <guilabel>Name</guilabel>
              </term>
              <listitem>
                <para>The name of the role. (Required)</para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>System-level permissions</guilabel>
              </term>
              <listitem>
                <itemizedlist>
                  <listitem>
                    <para>
                      With
                      <guilabel>Share to Everyone</guilabel>
                      set the role is allowed to share items to the
                      system-group 'Everyone'.
                    </para>
                  </listitem>
                  <listitem>
                    <para>
                      <guilabel>Act as another user</guilabel>
                      - property makes it possible for the one with this role
                      to login from the menu bar as another user. This is used
                      by job agents when they should act as the user who
                      started the job.
                    </para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>
                <guilabel>Description</guilabel>
              </term>
              <listitem>
                <para>Description and information about the role.(Optional)</para>
              </listitem>
            </varlistentry>
          </variablelist>
          <para>
            Set the properties and procceed then to either one of the other tabs or by
            clicking on one of the buttons:
            <guibutton>Save</guibutton>
            to save the changes or
            <guibutton>Cancel</guibutton>
            to abort.
          </para>
        </sect3>
        <seeother>
          <other external_id="role.edit.permissions">Role permissions</other>
          <other external_id="role.edit.members">Role members</other>
        </seeother>
      </helptext>
      
      <helptext external_id="role.edit.permissions" title="Edit role permissions">
        <sect3 id="user_administration.roles.edit.permissions">
          <title>Permissions</title>
          <para>
            A role's permissions are defined for each item type within BASE 2. 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
            checkboxes becomes disabled when selecting some of the item types
          </para>
          <para>
            After each item type is a string inside square brackets that shows what kind
            of permissions the current role has on that particular item type. The
            permissions that don't have been set are viewed with '-' inside the square
            brackets and those which have been set are represented with characters that
            are listed below.
          </para>
          <itemizedlist  spacing="compact">
            <listitem>
                <guilabel>DENIED</guilabel>
                = Deny access to the selected item. This exclude all the other
                permissions by unchecking the other check boxes.
            </listitem>
            <listitem>
                <guilabel>C</guilabel>
                = Create
            </listitem>
            <listitem>
                <guilabel>R</guilabel>
                = Read
            </listitem>
            <listitem>
                <guilabel>U</guilabel>
                = Use
            </listitem>
            <listitem>
                <guilabel>W</guilabel>
                = Write
            </listitem>
            <listitem>
                <guilabel>D</guilabel>
                = Delete
            </listitem>
            <listitem>
                <guilabel>O</guilabel>
                = Take ownership
            </listitem>
            <listitem>
                <guilabel>P</guilabel>
                = Set permission
            </listitem>
          </itemizedlist>
          <para>
            Set the role's permission on each one of the item types and procceed then to
            one of the other tabs or click on one of the buttons:
            <guibutton>Save</guibutton>
            to save the changes or
            <guibutton>Cancel</guibutton>
            to abort.
          </para>
        </sect3>
        <seeother>
          <other external_id="role.edit">Edit properties</other>
          <other external_id="role.edit.mebers">Role members</other>
        </seeother>
      </helptext>
      
      <helptext external_id="role.edit.members" title="Role members">
        <sect3>
          <title>Members</title>
          <para>
            Users that are members of a role are listed in the listbox located on this
            tab.Members can be added or removed with the two buttons, located to the
            right of the listbox,
            <guibutton>Add users&hellip;</guibutton>
            and
            <guibutton>Remove</guibutton>
            .
          </para>
          <variablelist>
            <varlistentry>
              <term>Add users to list</term>
              <listitem>
                <para>
                  Click on
                  <guibutton>Add users&hellip;</guibutton>
                  and select the users that should be added from the list in the
                  pop-up window. Press then on
                  <guibutton>Ok</guibutton>
                  button to close the pop-up window and add the selected users.
                  Use
                  <guibutton>Cancel</guibutton>
                  or just close the pop-up to abort and return to main window.
                </para>
              </listitem>
            </varlistentry>
            <varlistentry>
              <term>Remove users from list</term>
              <listitem>
                <para>
                  Members are removed from the list by first selecting them and
                  then pressing
                  <guibutton>Remove</guibutton>
                  . The selected user(s) are removed immediately.
                </para>
              </listitem>
            </varlistentry>
          </variablelist>
          <para>
            Press
            <guibutton>Save</guibutton>
            to save the role or go to one of the other tabs if there are more that needs
            to be set. Use
            <guibutton>Close</guibutton>
            to abort and close the window without saving the changes.
          </para>
        </sect3>
        <seeother>
          <other external_id="role.edit">Edit properties</other>
          <other external_id="role.edit.permissions">Role permissions</other>
        </seeother>
      </helptext>
    </sect2>
  </sect1>
  
  <sect1 id="user_administration.quota">
    <title>Disk space/quota</title>
    <para></para>
  </sect1>
</chapter>