sharing folders via vsc groups

source/accounts/vsc_user_groups.rst

@@ -3,6 +3,9 @@
 How to create/manage VSC groups
 ===============================
 
+
+.. _vsc_groups:
+
 What is a group?
 ----------------
 
@@ -28,12 +31,14 @@ organise themselves. Each VSC group has members and moderators:
    account page`_.  -  A moderator can add/delete members *and* moderators
 
    -  When you create a new group, you become both the first member and
-      moderator of that group.
+      the moderator of that group.
+
+.. warning::
 
-**Warning:** You should not exaggerate in creating new groups. Mounting
-file systems over NFS doesn't work properly if you belong to more than
-32 different groups, and so far we have not found a solution. This
-happens when you log on to a VSC cluster at a different site.
+   You should not exaggerate in creating new groups. Mounting
+   file systems over NFS doesn't work properly if you belong to more than
+   32 different groups, and so far we have not found a solution. This
+   happens when you log on to a VSC cluster at a different site.
 
 Managing groups
 ---------------
@@ -44,7 +49,7 @@ Viewing the groups you belong to
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 -  Go to the `VSC account page`_.
--  Click on "View groups".
+-  Click on the 'View Groups' tab.
 
 You will in fact see that you always belong to at least two groups
 depending on the institution from which you have your VSC account.
@@ -55,31 +60,27 @@ Join an existing group
 ~~~~~~~~~~~~~~~~~~~~~~
 
 -  Go to the `VSC account page`_.
--  Click on "New group"
--  Fill in the name of the group
-
-   -  The name of the group will automatically begin with the first
-      letter of the hosting institute (a for Antwerp, b for Brussels, g
-      for Ghent, l for Leuven)
-   -  If the name is wrong, it will treat the request as a new group
-
+-  Click on the 'New/Join Group' tab.
+-  Under the 'Join group' section, fill in the name of the group.
+   The name of the group will automatically begin with the first
+   letter of the hosting institute (a for Antwerp, b for Brussels, g
+   for Ghent, l for Leuven).
 -  In the message field, describe who you are to motivate the request,
-   so the moderator knows who is making the request
-
-   -  Moderators will deny all unclear requests
+   so the moderator knows who is making the request. Moderators will
+   deny all unclear requests.
 
 .. _create groups:
 
 Create new group
 ~~~~~~~~~~~~~~~~
 
 -  Go to the `VSC account page`_.
--  Click on "New group"
--  Fill in the group name
--  You will automatically become a member and moderator of the new group within an hour
+-  Click on the 'New/Join Group' tab.
+-  Fill in the group name.
+-  You will automatically become a member and moderator of the new group within an hour.
 -  Once you are a group moderator, you can manage your group by accepting
    requests from users that would like to join the group or inviting
-   users to join your group through the `VSC account page`_
+   users to join your group through the `VSC account page`_.
 
 .. _permissions groups:
 
@@ -108,10 +109,10 @@ Working with file and directory permissions
 
       ::
 
-         $ ls -l file
+         ls -l file
 
    -  ``-R``: Changes the modes of directories and files recursively.
-   -  Setting the setgid permission on a directory (chmod g+s) causes
+   -  Setting the setgid permission on a directory (``chmod g+s``) causes
       new files and subdirectories created within it to inherit its
       groupID, rather than the primary groupID of the user who created
       the file (the ownerID is never affected, only the groupID). Newly
@@ -124,5 +125,43 @@ Working with file and directory permissions
 
       ::
 
-         [user@foo]# find /path/to/directory -type d -exec chmod g+s '{}' \\;
+         find /path/to/directory -type d -exec chmod g+s '{}' \\;
+
+
+.. _sharing_via_vsc_groups:
+
+Sharing files and folders with other VSC users
+----------------------------------------------
+
+VSC users can share files/folders with other VSC users only via :ref:`VSC groups <vsc_groups>`.
+Imagine a VSC user who wants to share his post-processed data stored below the
+``$VSC_DATA/results/post-processed`` folder with another VSC user(s).
+Then, these are the steps to take:
+
+- Create a :ref:`new VSC group <create groups>` (if existing groups do not suit your purpose).
+  Let's call this new group ``lp_shared_data``.
+- Invite your VSC collaborators to join the group ``lp_shared_data``.
+- Change the group name of the folders in the hierarchy one by one to ``lp_shared_data``:
+
+  ::
+
+     chgrp lp_shared_data $VSC_DATA
+     chgrp lp_shared_data $VSC_DATA/results
+     # change group name recursively below the top hierarchy you want to share
+     chgrp -R lp_shared_data $VSC_DATA/results/post-processed
+
+- Make sure that the shared directory has read and execute access to all folders underneat,
+  and at least read access to all files:
+
+  ::
+
+     chmod -R g+r $VSC_DATA/results/post-processed
+     find $VSC_DATA/results/post-processed -type d -exec chmod g+x {} +
+
+- Depending on the internal agreement within the collaborating team, you may choose to additionally
+  allow the group members to add/remove files to/from the shared hierarchy. If so, the group
+  members are expected to be careful specifically in removing files. In that case:
+
+  ::
 
+     chmod -R g+w $VSC_DATA/results/post-processed

source/data/data_management_guidelines.rst

@@ -88,6 +88,10 @@ We recommend to gather your research team to draw the outlines of the DMP. Espec
 - at least some of the researchers using the HPC: they understand the day-to-day needs on the cluster
 - data support staff: for their technical expertise
 
+In case you collaborate with other VSC users and would like to share some files and folders
+with your team, you need to make extra changes in the group ownership and permissions.
+This is only possible using VSC groups; for more information please refer to 
+:ref:`sharing files and folders with other VSC users <sharing_via_vsc_groups>`.
 
 Structuring your files and directories
 ======================================