Shared documents are documents that different users can manipulate online via the web interface of Sympa, provided that they are authorized to do so. A shared document web space is associated with the list, and users can upload, download, delete, etc documents in that web space.
WWSympa's shared web features are fairly rudimentary. It is not our aim to provide a sophisticated tool for web publishing, such as those provided by products like Rearsite. It is nevertheless very useful to be able to define privileges on web documents in relation to list attributes such as subscribers, list owners or list editors.
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 why 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!
In order to have better control over the documents and to enforce security in the shared document web space, each document is linked to a set of specific control information: its access rights.
A list's shared documents are stored in the /home/sympa/list_data/mylist/shared
directory. This directory is either created via the Create shared
web admin feature, or at list creation time, if the list shared_doc
parameter is set. If you don't want the document repository to be created, you should remove the shared_doc
parameter from the corresponding create_list_templates/xx/config.tt2
files.
This chapter describes how the shared documents are managed, especially as regards their access rights. We will see:
Where shared documents are concerned, there are three kinds of operations which have the same constraints relating to access control:
If applied to a directory, it opens it and lists its contents (only the sub-documents the user is authorized to “see”).
If applied to a file, it downloads it, and in the case of a viewable file (text/plain, text/html, or image), displays it.
It allows:
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 online, describe it, replace or remove it.
The control operation is directly linked to the notion of access rights. If we want shared documents to be secure, we have to control the access to them. Not everybody must be authorized to perform every operation on 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.
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 over a document. Another possible control action on a document is therefore specifying who owns it.
The information (title, owner, access rights...) related 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 .desc
prefix.
The description file of a directory having the path mydirectory/mysubdirectory
has the path mydirectory/mysubdirectory/.desc
. The description file of a file having the path mydirectory/mysubdirectory/myfile.myextension
has the path mydirectory/mysubdirectory/.desc.myfile.myextension
.
The structure of a document (file or directory) description file is given below. You should never have to edit a description file.
title <description of the file in a few words> creation email <email 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>
The following example is for a document that subscribers can read, but that only the owner of the document and the owner of the list can edit.
title module C++ which uses the class List creation email foo@some.domain.com date_epoch 998698638 access read private edit owner
The public
scenario is the most permissive scenario. It enables anyone (including unknown users) to perform the corresponding action.
The private
scenario is the basic scenario for a shared space. Every subscriber of the list is authorized to perform the corresponding action. The private
scenario is the default read scenario for shared
when this shared space is created. This can be modified by editing the list configuration file.
The scenario owner
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 owner
scenario is the default scenario for editing.
The scenario editor
is for a moderated shared space for editing. Every suscriber of the list is allowed to edit a document. But this document will have to be installed or rejected by the editor of the list. Documents awaiting for moderation are visible by their author and the editor(s) of the list in the shared space. The editor has also an interface with all documents awaiting. When there is a new document, the editor is notified and when the document is installed, the author is notified too. In case of reject, the editor can notify the author or not.
Access control is an important operation performed every time a document is accessed within the shared space.
The access control related to a document in the hierarchy involves an iterative operation on all its parent directories.
The listmaster and privileged list owners are special users as regards the shared document web space. They are allowed to perform every action on every document. This privilege enables control over the shared space to be maintained. It is impossible to prevent the listmaster and privileged owners from performing any action they please on any document in the shared space.
In order to allow access to a root directory to be more restrictive than that of its subdirectories, the shared
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 the users authorized to edit a list's configuration may change access rights on its shared
directory.
mydirectory/mysubdirectory/myfile
is an arbitrary document in the shared space, but not in the root directory. A user X wishes to perform one of the three operations (read, edit, control) on this document. The access control will proceed as follows:
mydirectory/mysubdirectory/myfile
, X must be authorized to read every document making up the path; in other words, he/she must be allowed to read myfile
(the authorization scenario of the description file of myfile
must return do_it
for user X), and the same goes for mysubdirectory
and mydirectory
). mydirectory/mysubdirectory/myfile
may also have read operations performed on it by the owners of myfile
, mysubdirectory
, and mydirectory
. 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>)
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>)
X can control <a/b/c> if (X owner of <c> OR X owner of <b> OR X owner of <a>)
The shared web feature has called for some new actions.
D_ADMIN
d_admin
action is accessible from a list's admin page.D_READ
index
or index.htm
, and if the user has no permissions other than read on all subdocuments contained, the read action will consist in displaying the index. The d_read
action is accessible from a list's info page.D_CREATE_DIR
D_DESCRIBE
D_DELETE
D_UPLOAD
D_UNZIP
D_OVERWRITE
D_EDIT_FILE
and D_SAVE_FILE
D_CHANGE_ACCESS
D_SET_OWNER
The following template files have been created for the shared document web space.
The default page for reading a document. If for a file, displays it (if viewable) or downloads it. If for a directory, displays all readable subdocuments, each of which will feature buttons corresponding to the different actions this subdocument allows. If the directory is editable, displays buttons to describe it or upload a file into it. If the directory is editable without moderation, it displays buttons to create a new subdirectory or to upload a ZIP file in order to install a file hierarchy. If access to the document is editable, displays a button to edit the access to it.
The page used to edit a file. If for a text file, allows it to be edited online. This page also enables another file to be substituted in its place.
The page to edit the access rights and the owner of a document.
The page to upload a file is only used when the name of the file already exists.
This page is used to edit the description file and to rename it.