<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<!--Converted with LaTeX2HTML 99.2beta8 (1.42)
original version by: Nikos Drakos, CBLU, University of Leeds
* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
* with significant contributions from:
Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
<HTML>
<HEAD>
<TITLE>12. Shared documents</TITLE>
<META NAME="description" CONTENT="12. Shared documents">
<META NAME="keywords" CONTENT="sympa">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="Generator" CONTENT="LaTeX2HTML v99.2beta8">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<LINK REL="STYLESHEET" HREF="sympa.css">
<LINK REL="next" HREF="node14.html">
<LINK REL="previous" HREF="node12.html">
<LINK REL="up" HREF="sympa.html">
<LINK REL="next" HREF="node14.html">
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#ffffff">
<!--Navigation Panel-->
<A NAME="tex2html757"
HREF="node14.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html751"
HREF="sympa.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html745"
HREF="node12.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html753"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html755"
HREF="node17.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html758"
HREF="node14.html">13. Bounce management</A>
<B> Up:</B> <A NAME="tex2html752"
HREF="sympa.html">Sympa Mailing Lists Management Software</A>
<B> Previous:</B> <A NAME="tex2html746"
HREF="node12.html">11. List configuration parameters</A>
  <B> <A NAME="tex2html754"
HREF="node1.html">Contents</A></B>
  <B> <A NAME="tex2html756"
HREF="node17.html">Index</A></B>
<BR>
<BR>
<!--End of Navigation Panel-->
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
<UL>
<LI><A NAME="tex2html759"
HREF="node13.html#SECTION001310000000000000000">12.1 The three kind of operations on a document</A>
<LI><A NAME="tex2html760"
HREF="node13.html#SECTION001320000000000000000">12.2 The description file</A>
<UL>
<LI><A NAME="tex2html761"
HREF="node13.html#SECTION001321000000000000000">12.2.1 Structure of description files</A>
</UL>
<LI><A NAME="tex2html762"
HREF="node13.html#SECTION001330000000000000000">12.3 The predefined scenarii</A>
<UL>
<LI><A NAME="tex2html763"
HREF="node13.html#SECTION001331000000000000000">12.3.1 The public scenario</A>
<LI><A NAME="tex2html764"
HREF="node13.html#SECTION001332000000000000000">12.3.2 The private scenario</A>
<LI><A NAME="tex2html765"
HREF="node13.html#SECTION001333000000000000000">12.3.3 The scenario owner</A>
</UL>
<LI><A NAME="tex2html766"
HREF="node13.html#SECTION001340000000000000000">12.4 Access control</A>
<UL>
<LI><A NAME="tex2html767"
HREF="node13.html#SECTION001341000000000000000">12.4.1 Listmaster and privileged owners</A>
<LI><A NAME="tex2html768"
HREF="node13.html#SECTION001342000000000000000">12.4.2 Special case of the <TT>shared</TT> directory</A>
<LI><A NAME="tex2html769"
HREF="node13.html#SECTION001343000000000000000">12.4.3 General case</A>
</UL>
<LI><A NAME="tex2html770"
HREF="node13.html#SECTION001350000000000000000">12.5 Shared document actions</A>
<LI><A NAME="tex2html771"
HREF="node13.html#SECTION001360000000000000000">12.6 Template files</A>
<UL>
<LI><A NAME="tex2html772"
HREF="node13.html#SECTION001361000000000000000">12.6.1 d_read.tpl</A>
<LI><A NAME="tex2html773"
HREF="node13.html#SECTION001362000000000000000">12.6.2 d_editfile.tpl</A>
<LI><A NAME="tex2html774"
HREF="node13.html#SECTION001363000000000000000">12.6.3 d_control.tpl</A>
</UL></UL>
<!--End of Table of Child-Links-->
<HR>
<H1><A NAME="SECTION001300000000000000000"></A>
<A NAME="shared"></A> <A NAME="2028"></A>
<BR>
12. Shared documents
</H1>
<P>
Shared documents are documents that different users can manipulate
on-line via the web interface of <I>Sympa</I>, provided that the are authorized
to do so. A shared space is associated with a list, and users of the list
can upload, download, delete, etc, documents in the shared space.
<P>
<A NAME="5194"></A><I>WWSympa</I> shared web features are fairly rudimentary. It is not our aim to provide
a sophisticated tool for web publishing, such as are provided by products
like <I>Rearsite</I>.
It is nevertheless very useful to be able to define privilege on
web documents in relation to list attributes such as <I>subscribers</I>,
<I>list owners</I>, or <I>list editors</I>.
<P>
All file and directory names are lowercased by Sympa. It is consequently
impossible to create two different documents whose names differ only
in their case. The reason Sympa does this is to allow correct URL links
even when using an HTML document generator (typically Powerpoint) which uses
random case for file names!
<P>
In order to have better control over the documents in
the shared space, each document is linked to a set of specific control information :
its access rights. Security is thus ensured.
<P>
A list's shared documents are stored in the <A NAME="5197"></A><TT>~sympa/expl/mylist/shared</TT>
directory.
<P>
This chapter describes how the shared documents are managed,
especially as regards their access rights.
We shall see :
<P>
<UL>
<LI>the kind of operations which can be performed on shared documents
<P>
</LI>
<LI>access rights management
<P>
</LI>
<LI>access rights control specifications
<P>
</LI>
<LI>actions on shared documents
<P>
</LI>
<LI>template files
</LI>
</UL>
<P>
<H1><A NAME="SECTION001310000000000000000"></A>
<A NAME="shared-operations"></A>
<BR>
12.1 The three kind of operations on a document
</H1>
Where shared documents are concerned, there are three kinds of operation which
have the same constraints relating to access control :
<UL>
<LI>The read operation :
<BR>
<UL>
<LI>If a directory, open it and list its contents (only those
sub-documents the user is authorized to ``see'').
</LI>
<LI>If a file, download it, and if a viewable file (<I>text/plain</I>, <I>text/html</I>,
or image), display it.
</LI>
</UL>
</LI>
<LI>The edit operation :
<BR>
<UL>
<LI>Subdirectory creation
</LI>
<LI>File uploading
</LI>
<LI>Description of a document (title and basic information)
</LI>
<LI>On-line editing of a text file
</LI>
<LI>Document (file or directory) removal. If a directory, it must be empty.
</LI>
</UL>
These different edit actions are equivalent as regards access rights. Users who are
authorized to edit a directory can create a subdirectory or upload a file to it,
as well as describe or delete it. Users authorized to edit a file can edit
it on-line, describe it, replace or remove it.
</LI>
<LI>The control operation :
<BR>
The control operation is directly linked to the notion of access rights. If we wish
shared documents to be secure, we have to control the access to them. Not everybody
must be authorized to do everything to them. Consequently, each document has
specific access rights for reading and editing. Performing a control action on a document
involves changing its Read/Edit rights.
<BR>
The control operation has more restrictive access rights than the other two operations.
Only the owner of a document, the privileged owner of the list and the listmaster have
control rights on a document. Another possible control action on a document is therefore
specifying who owns it.
</LI>
</UL>
<P>
<H1><A NAME="SECTION001320000000000000000"></A>
<A NAME="shared-desc-file"></A>
<BR>
12.2 The description file
</H1>
The information (title, owner, access rights...) relative to each document must be stored, and so
each shared document is linked to a special file called a description file, whose name includes
the <A NAME="5202"></A><TT>.desc</TT> prefix.
<P>
The description file of a directory having the path <A NAME="5205"></A><TT>mydirectory/mysubdirectory</TT> has the path
<A NAME="5208"></A><TT>mydirectory/mysubdirectory/.desc</TT> .
The description file of a file having the path <A NAME="5211"></A><TT>mydirectory/mysubdirectory/myfile.myextension</TT> has the path
<A NAME="5214"></A><TT>mydirectory/mysubdirectory/.desc.myfile.myextension</TT> .
<P>
<H2><A NAME="SECTION001321000000000000000">
12.2.1 Structure of description files</A>
</H2>
<P>
The structure of a document (file or directory) description file is given below.
You should <I>never</I> have to edit a description file.
<P><PRE>
title
<description of the file in a few words>
creation
email <e-mail of the owner of the document>
date_epoch <date_epoch of the creation of the document>
access
read <access rights for read>
edit <access rights for edit>
</PRE>
<P>
The following example is for a document that subscribers can read, but which only the owner of the document
and the owner of the list can edit.<PRE>
title
module C++ which uses the class List
creation
email foo@some.domain.com
date_epoch 998698638
access
read private
edit owner
</PRE>
<P>
<H1><A NAME="SECTION001330000000000000000"></A>
<A NAME="shared-scenarii"></A>
<BR>
12.3 The predefined scenarii
</H1>
<P>
<H2><A NAME="SECTION001331000000000000000">
12.3.1 The public scenario</A>
</H2>
The <B>public</B> scenario is the most permissive scenario. It enables anyone (including
unknown users) to perform the corresponding action.
<P>
<H2><A NAME="SECTION001332000000000000000">
12.3.2 The private scenario</A>
</H2>
The <B>private</B> scenario is the basic scenario for a shared space. Every subscriber of
the list is authorized to perform the corresponding action. The <B>private</B> scenario is the default
read scenario for <A NAME="5217"></A><TT>shared</TT> when this shared space is created. This can be modified by editing
the list configuration file.
<P>
<H2><A NAME="SECTION001333000000000000000">
12.3.3 The scenario owner</A>
</H2>
The scenario <B>owner</B> is the most restrictive scenario for a shared space.
Only the listmaster, list owners and the owner of the document
(or those of a parent document) are allowed to perform the corresponding action.
The <B>owner</B> scenario is the default scenario for editing.
<P>
<H1><A NAME="SECTION001340000000000000000"></A>
<A NAME="shared-access"></A>
<BR>
12.4 Access control
</H1>
Access control is an important operation performed
every time a document within the shared space is accessed.
<P>
The access control relative to a document in the hierarchy involves an iterative
operation on all its parent directories.
<P>
<H2><A NAME="SECTION001341000000000000000">
12.4.1 Listmaster and privileged owners</A>
</H2>
The listmaster and privileged list owners are special users in the shared
web. They are allowed to perform every action on every document in
the shared space. This privilege enables control over
the shared space to be maintained. It is impossible to prevent the listmaster and
privileged owners from performing whatever action they please on any document
in the shared space.
<P>
<H2><A NAME="SECTION001342000000000000000"></A><A NAME="5220"></A>
<BR>
12.4.2 Special case of the <TT>shared</TT> directory
</H2>
In order to allow access to a root directory to be more restrictive than
that of its subdirectories, the <A NAME="5223"></A><TT>shared</TT> directory (root directory) is
a special case as regards access control.
The access rights for read and edit are those specified in the list configuration file.
Control of the root directory is specific.
Only those users authorized to edit a list's configuration may change access rights on
its <A NAME="5226"></A><TT>shared</TT> directory.
<P>
<H2><A NAME="SECTION001343000000000000000">
12.4.3 General case</A>
</H2>
<A NAME="5229"></A><TT>mydirectory/mysubdirectory/myfile</TT> is an arbitrary document in the shared space,
but not in the <I>root</I> directory. A user <B>X</B> wishes to perform one
of the three operations (read, edit, control) on this document.
The access control will proceed as follows :
<UL>
<LI>Read operation
<BR>
To be authorized to perform a read action on
<A NAME="5232"></A><TT>mydirectory/mysubdirectory/myfile</TT>, <B>X</B> must be
authorized to read every document making up the path; in other words, she
must be allowed to read <A NAME="5235"></A><TT>myfile</TT> (the scenario of the description file
of <A NAME="5238"></A><TT>myfile</TT> must return <I>do_it</I> for user <B>X</B>), and the
same goes for <A NAME="5241"></A><TT>mysubdirectory</TT> and <A NAME="5244"></A><TT>mydirectory</TT>).
<BR>
In addition, given that the owner of a document or one of its parent directories
is allowed to perform <B>all actions on that document</B>,
<A NAME="5247"></A><TT>mydirectory/mysubdirectory/myfile</TT> may also have read operations performed
on it by the owners of <A NAME="5250"></A><TT>myfile</TT>, <A NAME="5253"></A><TT>mysubdirectory</TT>,
and <A NAME="5256"></A><TT>mydirectory</TT>.
<P>
This can be schematized as follows :<PRE>
X can read <a/b/c>
if
(X can read <c>
AND X can read <b>
AND X can read <a>)
OR
(X owner of <c>
OR X owner of <b>
OR X owner of <a>)
</PRE>
<P>
</LI>
<LI>Edit operation
<BR>
The access algorithm for edit is identical to the algorithm for read :<PRE>
X can edit <a/b/c>
if
(X can edit <c>
AND X can edit <b>
AND X can edit <a>)
OR
(X owner of <c>
OR X owner of <b>
OR X owner of <a>)
</PRE>
<P>
</LI>
<LI>Control operation
<BR>
The access control which precedes a control action (change rights
or set the owner of a document) is much more restrictive.
Only the owner of a document or the owners of a parent
document may perform a control action :<PRE>
X can control <a/b/c>
if
(X owner of <c>
OR X owner of <b>
OR X owner of <a>)
</PRE>
<P>
</LI>
</UL>
<P>
<H1><A NAME="SECTION001350000000000000000">
12.5 Shared document actions</A>
</H1>
<P>
The shared web feature has called for some new actions.
<UL>
<LI>action D_ADMIN
<BR>
Create the shared web, close it or restore it. The d_admin action is accessible
from a list's <B>admin</B> page.
</LI>
<LI>action D_READ
<BR>
Reads the document after read access control. If a folder, lists all the subdocuments that can
be read. If a file, displays it if it is viewable, else downloads it to disk.
If the document to be read contains a file named <A NAME="5259"></A><TT>index.html</TT> or <A NAME="5262"></A><TT>index.htm</TT>, and if
the user has no permissions other than read on all contained subdocuments, the read action will
consist in displaying the index.
The d_read action is accessible from a list's <B>info</B> page.
</LI>
<LI>action D_CREATE_DIR
<BR>
Creates a new subdirectory in a directory that can be edited.
The creator is the owner of the directory. The access rights are
those of the parent directory.
</LI>
<LI>action D_DESCRIBE
<BR>
Describes a document that can be edited.
</LI>
<LI>action D_DELETE
<BR>
Deletes a document after edit access control. If a folder, it has to be empty.
</LI>
<LI>action D_UPLOAD
<BR>
Uploads a file into a directory that can be edited.
</LI>
<LI>action D_OVERWRITE
<BR>
Overwrites a file if it can be edited. The new owner of the file is the one who has done
the overwriting operation.
</LI>
<LI>actions D_EDIT_FILE and D_SAVE_FILE
<BR>
Edits a file and saves it after edit access control. The new owner of the file is the one
who has done the saving operation.
</LI>
<LI>action D_CHANGE_ACCESS
<BR>
Changes the access rights of a document (read or edit), provided that control of this document is
authorized.
</LI>
<LI>action D_SET_OWNER
<BR>
Changes the owner of a directory, provided that control of this document is
authorized. The directory must be empty. The new owner can be anyone, but authentication is necessary
before any action may be performed on the document.
<P>
</LI>
</UL>
<P>
<H1><A NAME="SECTION001360000000000000000">
12.6 Template files</A>
</H1>
The following template files have been created for the shared web:
<P>
<H2><A NAME="SECTION001361000000000000000">
12.6.1 d_read.tpl</A>
</H2>
The default page for reading a document. If a file, displays it (if
viewable) or downloads it. If a directory, displays all readable
subdocuments, each of which will feature buttons corresponding
to the different actions this sub document allows. If the directory is
editable, displays buttons to describe it, upload a file to it
and, create a new subdirectory. If access to the document is editable,
displays a button to edit the access to it.
<P>
<H2><A NAME="SECTION001362000000000000000">
12.6.2 d_editfile.tpl</A>
</H2>
The page used to edit a file. If a text file, allows it to be edited on-line.
This page also enables the description of the file to be edited, or another file
to be substituted in its place.
<P>
<H2><A NAME="SECTION001363000000000000000">
12.6.3 d_control.tpl</A>
</H2>
The page to edit the access rights and the owner of a document.
<P>
<HR>
<!--Navigation Panel-->
<A NAME="tex2html757"
HREF="node14.html">
<IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
<A NAME="tex2html751"
HREF="sympa.html">
<IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
<A NAME="tex2html745"
HREF="node12.html">
<IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
<A NAME="tex2html753"
HREF="node1.html">
<IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
<A NAME="tex2html755"
HREF="node17.html">
<IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
<BR>
<B> Next:</B> <A NAME="tex2html758"
HREF="node14.html">13. Bounce management</A>
<B> Up:</B> <A NAME="tex2html752"
HREF="sympa.html">Sympa Mailing Lists Management Software</A>
<B> Previous:</B> <A NAME="tex2html746"
HREF="node12.html">11. List configuration parameters</A>
  <B> <A NAME="tex2html754"
HREF="node1.html">Contents</A></B>
  <B> <A NAME="tex2html756"
HREF="node17.html">Index</A></B>
<!--End of Navigation Panel-->
<ADDRESS>
root
2001-06-05
</ADDRESS>
</BODY>
</HTML>
distrib
>
Mandriva
>
8.2
>
i586
>
media
>
contrib
>
by-pkgid
>
968fb36a1d13190d5ed9d2ee3bf64b87
>
files
>
81
