Quick Links Principal Investigators Group Owners Group Members File Ownership/Permissions Approaches to Data Management Best Practices Troubleshooting/FAQ Additional Information

Many Biowulf users are working on projects with other Biowulf users, who may be in the same lab, same IC, or in other NIH ICs. A group of users may need to share data, software installations, and scripts on a regular basis. The best way to approach this kind of workload is to set up a group with a shared directory. All groups have a group owner and group members. The group owner and members must all have Biowulf accounts. The group owner is the only person in the group who can request the addition or deletion of users from the group, and who can apply for a quota increase for the shared directory. To apply for a shared group and an associated data directory, the group owner should fill out the online form at https://hpcnihapps.cit.nih.gov/auth/dashboard/shared_data_request.php

The Principal Investigator (PI) of the group owner has the final responsibility for data in the shared group directory. If there are questions about the ownership of any of the data, or if all the group members leave, the PI is responsible for decisions about the disposition of the data.

The group owner is the first member listed in the group. Via the HPC Dashboard, this person will be able to check the members of the group, and make the following changes. Only the group owner (or the PI) can request such changes.

Add and delete group members

Request quota increases

The shared group directory is initially set up to be owned by the group owner, with read-write-execute permission by the group members. e.g.

drwxrws---. 6 groupowner XYZLab 4096 Aug 10 15:13 /gs6/users/XYZLab/

drwxrws---.

Group members are responsible for any data that they write into the shared directory. They should:

• Make sure that their umask is set as agreed with the group owner.
• Make sure that their jobs are writing files with group read permissions.
• Before they leave the group or leave NIH, ensure that unnecessary data is deleted.
• Before they leave the group or leave NIH, ensure that all files they own in the shared group directory are readable by members of the group.

If the group directory is nearing or hits its quota limit, an alert email will go out to all members of the group.

Each Biowulf user is responsible for ensuring proper group ownerships are applied and file permissions are appropriately set in shared directories.

A common problem is when a group member miss sets permissions on a file or directory, and other group members are unable to read it.

If the owner of the file is still in the group

Please contact the file owner to get the permissions fixed. By policy, the HPC staff will not change the group or permissions of files/directories in this situation.

If the owner of the file is no longer in the group

In this situation, the group owner can request the HPC staff to modify the ownership or permissions of the file, by sending email to staff@hpc.nih.gov. Only the group owner can make this request.

Approaches to data management in the shared group directory

If the group owner and group members are not familiar with Unix permissions and umasks, it is highly recommended that they read through Data Management for Groups, which describes in detail some approaches to data management, how to set and manage permissions, and how to fix problems.

Within the shared directory, some groups may want all group members to have read-write access to all subdirectories. In that case, all group members should be sure to set their umask appropriately, e.g. by setting

umask 007

either in their /home/$USER/.bashrc (which then applies to all jobs and all login sesssions thereafter), or for a particular session. See here for a more thorough explanation of startup files.

Other groups may want subdirectories owned by each group member with only read access for other group members, e.g.

The group owner should ensure that each member of the group follows best practices for management of the group directory.

Best Practices for Groups

• At the time of requesting the group shared directory, consider how it will be set up and used. Will all the group members need to access all the files, or will there be subdirectories for each group member? Come up with a plan for subdirectories (per project? per group member?)
• No more than 5000 files per directory.
• File and directory names should be systematic and logical (and, ideally, parseable by programs or scripts).
• Document data as it is added. (e.g. in a README file in each directory)
• Use tar/gzip to compress directories that are not in use, or at the end of a project, and download them to a lab server or IC archive. Give the tarball a meaningful name including a date and time.
• Note that HPC /data areas are intended for current data only. There are snapshots on data directories to help with inadvertent file deletion, but there are no longterm backups of data directories. Archival data (after a project has completed) or old, unused data should not be stored on HPC storage.

Troubleshooting/FAQ

1. "I get a permission denied error trying to access a folder in our shared data area."
   Solution: The owner of the folder should use the chgrp or chmod command to update the group permissions on the folder.

   Explanation: The most likely issue is that the group of the folder is not set to the desired group. By default, all folders in the shared data area are configured to inherit the group by setting the setgid permission. This works well when files or folders are created in the data share directory. However, if a folder or file are copied or moved into the shared directory, the group and permissions may need to be manually configured. The ls -l command is useful to see the ownership and permissions of the file (ls -ld for a folder) For a full description of the ls output, see our Unix Permissions documentation. A second possibility are the lack of group read and execute permissions. Due to the default permissions on the HPC system, this is less common. If a directory does not have the correct group or permissions, you should contact the file owner to get them updated.

2. "I can read files from a shared data area but get a permission denied error writing to the folder."
   Solution: The owner of the directory should use the chmod command to add write permissions to the folder.

   Explanation: The most likely issue is the group permissions on the folder do not allow group write access. The ls -ld command is useful to see what the group permissions are on a folder. If a directory does not have the expected group permissions, you should contact the folder owner to have them updated the group permissions. For a full description of the chmod command, see our Permission Mode documentation.

3. "When I create a new folder in the shared data area, other group members cannot write to it."
   Solution: If you would like to allow group write permissions by default, you may add the following line to your ~/.bashrc file.

   umask 007

   Explanation: The root of the problem are the default group permissions (see FAQ #2). The default permissions set on a file or directory is determined by the current setting of umask. For security purposes, the default umask does not allow group write permissions. For a full description of default permissions, see our umask documentation. If you wish to modify your default permissions, it is important to read and understand the umask documentation implications.

   If a folder has been created with the wrong permissions, they can be fixed later by using chmod.

4. "When I create a new folder in the shared data area, it does not have the correct group owner."
   Solution: The set-gid bit can be used on the parent directory to enforce inheritance of group-ownership on new files or folders.

   Explanation: The set-gid bit forces new files or folders to inherit the group owner of the parent folder. By default, all top level shared data directories are configured with the set-git bit enabled. This means any file or folder created in the top level data share directory will inherit the correct group-owner. In some situations, the set-gid bit of child directories can become unset. Once the set-gid is unset, new files or folders will be group-owned by the default group of the user.

   The set-gid bit is denoted by an 's' in the group-execute field of a folder. To add the set-gid bit to a folder, use:

   chmod g+s $directory_name

   For a full description of the set-gid, see our Unix Permissions documentation.

5. How to coordinate permissions on files in the shared directory?
   If one member of the group needs read or write access to another member's files, have the members talk to each other and agree on permission settings. The owners of the files need to set or change the permissions.

6. What happens if a group member leaves NIH?
   Ideally, before the person leaves NIH, the group owner and group members should check on all the data in the shared directory that is owned by the departing group member. Delete any data that is not needed, and ensure that all remaining data has group read-write-execute permissions. This will ensure that after the person leaves NIH and their Biowulf account is deleted, all the important data is still accessible to members of the group.

7. What happens if the group owner leaves NIH?
   The ownership of the group passes to the next member listed in the group. This person will now have the responsibilities of the group owner as described above. If this is not desired, and the group decides to have another person as the group owner, please contact staff@hpc.nih.gov to request a change of group ownership.

8. What happens if all the group members leave NIH?
   If all group members leave NIH, the group will be empty. Hopefully, the group members have appropriately downloaded all the data that is needed, and cleaned up the shared group directory.

   If there is still data left in the shared group directory, the HPC staff will contact the responsible PI (the PI of the last group owner) to discuss downloading/deleting of any remaining data.

• Data Management for Groups (PDF). Handout/slides from a class taught by David Hoover of the HPC Staff, 2019.
• Managing Access Permissions on Biowulf
• Sharing Data with Collaborators