Workspaces/Advanced Features: Difference between revisions

From bwHPC Wiki
Jump to navigation Jump to search
mNo edit summary
 
(21 intermediate revisions by the same user not shown)
Line 54: Line 54:
|}
|}


== Detailed Topics ==
== Multiple Filesystem Locations ==


=== Commands ===
{| class="wikitable"
|-
!style="width:40%" | Works on cluster
!style="width:10%" | bwUC 3.0
!style="width:10%" | BinAC2
!style="width:10%" | Helix
!style="width:10%" | JUSTUS 2
!style="width:10%" | NEMO2
|-
|<tt>-F</tt> option (multiple filesystems)
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#FFB6C1; text-align:center;" | ✗
|style="background-color:#FFB6C1; text-align:center;" | ✗
|style="background-color:#FFB6C1; text-align:center;" | ✗
|style="background-color:#FFB6C1; text-align:center;" | ✗
|}


* '''[[Workspaces/Advanced_Features/ws_allocate|ws_allocate]]''' - Create and extend workspaces (detailed options)
Some clusters offer multiple filesystem locations for workspaces with different characteristics:
* '''[[Workspaces/Advanced_Features/ws_list|ws_list]]''' - List workspaces (sorting, filtering)
* '''[[Workspaces/Advanced_Features/ws_find|ws_find]]''' - Find workspace paths for scripts
* '''[[Workspaces/Advanced_Features/ws_extend|ws_extend]]''' - Extend workspace lifetime
* '''[[Workspaces/Advanced_Features/ws_release|ws_release]]''' - Release (delete) workspaces with immediate deletion options
* '''[[Workspaces/Advanced_Features/ws_restore|ws_restore]]''' - Restore expired or released workspaces
* '''[[Workspaces/Advanced_Features/ws_register|ws_register]]''' - Create symbolic links to workspaces


=== Configuration & Features ===
'''bwUniCluster 3.0:'''
* Default workspace filesystem (Lustre)
* Flash-based workspace filesystem (<tt>ffuc</tt>) - for KIT/HoreKa users only
** Lower latency and better performance for small files
** SSDs instead of hard disks
** Shared between bwUniCluster 3.0 and HoreKa


* '''[[Workspaces/Advanced_Features/Filesystems|Multiple Filesystem Locations]]''' - Choosing the right filesystem for your workload
'''Example creating workspace on flash filesystem:'''
* '''[[Workspaces/Advanced_Features/Reminders|Reminders & Configuration]]''' - Email reminders and ~/.ws_user.conf setup
* '''[[Workspaces/Advanced_Features/Sharing|Sharing Workspaces]]''' - Group workspaces, ws_share, ACLs, Unix permissions
* '''[[Workspaces/Advanced_Features/Quotas|Quotas & Limits]]''' - Cluster-specific limits and checking quotas


=== Best Practices ===
$ ws_allocate -F ffuc myworkspace 60


* '''[[Workspaces/Advanced_Features/Best_Practices|Best Practices]]''' - Recommendations for different use cases
Use <tt>ws_list -l</tt> or <tt>ws_find -l</tt> to see available filesystem locations on your cluster.


== Detailed ws_allocate Options ==
== Quick Navigation ==


=== By Task ===
{| class="wikitable"
|-
!style="width:40%" | Works on cluster
!style="width:10%" | bwUC 3.0
!style="width:10%" | BinAC2
!style="width:10%" | Helix
!style="width:10%" | JUSTUS 2
!style="width:10%" | NEMO2
|-
|<tt>ws_allocate -x -u</tt> (extend other user's workspace)
| style="text-align:center;" |
| style="text-align:center;" |
| style="text-align:center;" |
| style="text-align:center;" |
|style="background-color:#90EE90; text-align:center;" | ✓
|}


'''Creating and Managing:'''
=== Basic Usage ===
* Create workspace → [[Workspaces#Create_Workspace|Basic]] | [[Workspaces/Advanced_Features/ws_allocate|Advanced]]
* List workspaces → [[Workspaces#List_Your_Workspaces|Basic]] | [[Workspaces/Advanced_Features/ws_list|Advanced]]
* Extend lifetime → [[Workspaces#Extend_Workspace_Lifetime|Basic]] | [[Workspaces/Advanced_Features/ws_extend|Advanced]]
* Release workspace → [[Workspaces#Release_.28Delete.29_Workspace|Basic]] | [[Workspaces/Advanced_Features/ws_release|Advanced]]
* Restore workspace → [[Workspaces#Restore_Workspace|Basic]] | [[Workspaces/Advanced_Features/ws_restore|Advanced]]


'''Collaboration:'''
Execution of:
* Work with groups → [[Workspaces#Work_with_Groups_.28Share_Workspaces.29|Basic]] | [[Workspaces/Advanced_Features/Sharing#Group_Workspaces|Advanced]]
* Share with users → [[Workspaces/Advanced_Features/Sharing#Sharing_with_ws_share|ws_share]] | [[Workspaces/Advanced_Features/Sharing#ACLs:_Access_Control_Lists|ACLs]] | [[Workspaces/Advanced_Features/Sharing#Regular_Unix_Permissions|Unix Permissions]]


'''Configuration:'''
$ ws_allocate myWs 30
* Email reminders → [[Workspaces/Advanced_Features/Reminders|Reminders]]
* Default settings → [[Workspaces/Advanced_Features/Reminders#Configuration_File:_.7E.2F.ws_user.conf|~/.ws_user.conf]]
* Workspace links → [[Workspaces/Advanced_Features/ws_register|ws_register]]


'''Resources:'''
e.g. returns:
* Filesystem selection → [[Workspaces/Advanced_Features/Filesystems|Filesystems]]
* Check quotas → [[Workspaces/Advanced_Features/Quotas#Checking_Workspace_Quotas|Quota Commands]]
Workspace created. Duration is 720 hours.
* Cluster limits → [[Workspaces/Advanced_Features/Quotas|Quotas & Limits]]
Further extensions available: 3
/work/workspace/scratch/username-myWs-0


=== By Experience Level ===
The command returns the path to the new directory, which can be captured in a variable:


'''Beginners:'''
$ SCRDIR=$(ws_allocate myWs 10)
* Start with the main [[Workspaces]] guide
* Review [[Workspaces/Advanced_Features/Best_Practices|Best Practices]]


'''Intermediate Users:'''
'''Important:''' Creating a workspace a second time with the same command is a no-operation - it always returns the same path. This makes it safe and encouraged to use such a line in batch jobs which are part of a series of jobs working on the same data, no matter if the job was running before or not.
* [[Workspaces/Advanced_Features/Filesystems|Choose optimal filesystem]]
* [[Workspaces#Work_with_Groups_.28Share_Workspaces.29|Set up group workspaces]]
* [[Workspaces/Advanced_Features/ws_allocate#Using_Workspaces_in_Batch_Jobs|Use in batch jobs]]
* [[Workspaces/Advanced_Features/ws_restore#Helix-specific_-_Workspace_Snapshots|Snapshot recovery (Helix)]]


'''Advanced Users:'''
=== All Options and When to Use Them ===
* [[Workspaces/Advanced_Features/Sharing|Advanced sharing methods]] (ACLs)

* [[Workspaces/Advanced_Features/ws_release#Immediate_Deletion_.28Free_Quota_Instantly.29|Immediate deletion for quota management]]
{| class="wikitable"
* Set up [[Workspaces/Advanced_Features/Reminders#Configuration_File:_.7E.2F.ws_user.conf|~/.ws_user.conf]]
|-
!style="width:20%" | Option
!style="width:40%" | Description
!style="width:40%" | When to Use
|-
|<tt>-F <filesystem></tt>
|Specify the filesystem where the workspace should be created
|'''Optional''' - Most clusters have only one default filesystem. Use only when you need specific storage characteristics (speed, capacity) or to balance load across multiple filesystems. List available locations with <tt>ws_list -l</tt> or <tt>ws_find -l</tt>
|-
|<tt>-g</tt>
|Create a group-readable workspace
|'''Recommended''' when working in a team and others need to read your data. The workspace will be visible to group members with <tt>ws_list -g</tt>
|-
|<tt>-G <groupname></tt>
|Create a group-writable workspace with sticky bit
|'''Recommended''' for collaborative work where team members need to write data. Ensures all created files belong to the group. Can be set as default in <tt>~/.ws_user.conf</tt>
|-
|<tt>-m <mailaddress></tt>
|Set email address for reminders
|'''Optional''' - Email addresses come from your identity provider. Only use this option to override with a different address. Can be set as default in <tt>~/.ws_user.conf</tt>
|-
|<tt>-r <days></tt>
|Set reminder to be sent n days before expiration
|'''Optional''' - Email reminders are sent automatically. Use this only to customize when the reminder starts (e.g., 3, 5, or 7 days before). Can be set as default in <tt>~/.ws_user.conf</tt>
|-
|<tt>-x</tt>
|Extend an existing workspace
|Use when you need more time. Each extension consumes one of the available extensions
|-
|<tt>-u <username></tt>
|Used with <tt>-x</tt> to extend another user's workspace
|Use when a group member is absent and their shared workspace needs extension. Requires group write access <tt>-G</tt>
|-
|<tt>-c <comment></tt>
|Add a comment to the workspace
|Use to document the purpose of the workspace for yourself and collaborators
|-
|<tt>-d <duration></tt>
|Duration in days (alternative to positional argument)
|Use if you prefer explicit option syntax: <tt>ws_allocate -n myWs -d 30</tt>
|-
|<tt>-n <name></tt>
|Workspace name (alternative to positional argument)
|Use if you prefer explicit option syntax: <tt>ws_allocate -n myWs -d 30</tt>
|}

=== Duration Settings ===

If you do not specify a lifetime, a default lifetime will be used (see the [[Workspaces/Advanced_Features#Cluster-Specific_Workspace_Limits|Cluster-Specific Workspace Limits]])). The maximum lifetime may be limited by the operations team. If you specify a longer lifetime, it will be capped to the maximum, and you will see a message that it was changed.

For more information read the program's help: <tt>$ ws_allocate -h</tt> or <tt>man ws_allocate</tt>

== Advanced ws_list Options ==

Beyond the basic options shown in the main [[Workspaces]] guide, <tt>ws_list</tt> supports additional sorting and filtering:

* <tt>-N</tt> - Sort by name (alphabetical)
* <tt>-C</tt> - Sort by creation date
* <tt>-t</tt> - Terse format
* <tt>-v</tt> - Verbose format with all metadata
* <tt>-r</tt> - Reverse sort order
* <tt>-F <location></tt> - List workspaces on specific filesystem only
* <tt>-g</tt> - List group workspaces (if you're in the same group)
* <tt>-l</tt> - List available filesystem locations

To list expired workspaces, see [[#Restore_an_Expired_Workspace|Restore an Expired Workspace]].

For more information: <tt>$ ws_list -h</tt> or <tt>man ws_list</tt>

== Advanced ws_find Options ==

<tt>ws_find</tt> can search workspaces on specific filesystems:

* <tt>-F <filesystem></tt> - Search workspace on specific filesystem
* <tt>-l</tt> - List valid filesystem names

== Advanced ws_extend Options ==

Beyond the basic extension shown in the main [[Workspaces]] guide:

* <tt>-F filesystem</tt> - Extend workspace on specific filesystem
* <tt>ws_allocate -x</tt> - Alternative command for extension
* You can shorten workspace lifetime even if no extensions are available
* Group members can extend group workspaces. Requires group write access <tt>ws_allocate -G</tt>:
<tt>ws_allocate -x -u <username> <workspace_id> <days></tt>

'''Update reminder only''' (without extending):

$ ws_allocate -r <days> -x <workspace> 0

== Getting Reminders ==

{| class="wikitable"
|-
!style="width:40%" | Works on cluster
!style="width:10%" | bwUC 3.0
!style="width:10%" | BinAC2
!style="width:10%" | Helix
!style="width:10%" | JUSTUS 2
!style="width:10%" | NEMO2
|-
|Email reminders
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|-
|<tt>ws_send_ical</tt> (calendar reminders)
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#FFB6C1; text-align:center;" | ✗
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#FFB6C1; text-align:center;" | ✗
|style="background-color:#FFB6C1; text-align:center;" | ✗
|}

'''Email reminders:''' Sent automatically using email addresses from your identity provider. You can customize the reminder timing with <tt>-r <days></tt>:

$ ws_allocate -r 7 myWs 30 # Reminder 7 days before expiry
$ ws_allocate -r 3 -m custom@example.com myWs 30 # Custom timing and different email address

'''Calendar reminder''' (bwUniCluster 3.0, Helix):

$ ws_send_ical <workspace> <email>

'''User defaults''' in <tt>~/.ws_user.conf</tt> (YAML format):

<pre>
mail: reach@me.here # Optional - only if you want to override the email from identity provider
duration: 10 # Default workspace lifetime
reminder: 3 # Days before expiration to send reminder
groupname: mygroup # Default group for -G option
</pre>

=== Example ~/.ws_user.conf Configuration ===

{| class="wikitable"
|-
!style="width:40%" | Works on cluster
!style="width:10%" | bwUC 3.0
!style="width:10%" | BinAC2
!style="width:10%" | Helix
!style="width:10%" | JUSTUS 2
!style="width:10%" | NEMO2
|-
|<tt>~/.ws_user.conf</tt> configuration file
|style="background-color:#90EE90; text-align:center;" | ✓
|style="text-align:center;" |
|style="text-align:center;" |
|style="text-align:center;" |
|style="background-color:#90EE90; text-align:center;" | ✓
|}

Here's a complete example configuration file that sets useful defaults:

'''Important:''' Some versions of the workspace tools mistakenly interpret a leading comment line in <tt>~/.ws_user.conf</tt> as an email address. Make sure the '''first line does not start with <tt>#</tt>'''. Start with a setting like <tt>duration: 30</tt>; inline end-of-line comments are fine.

<pre>
duration: 30 # Default workspace lifetime (first line must not start with #)
# ~/.ws_user.conf - Workspace tool defaults
# This file uses YAML syntax

# Email address for expiration reminders (optional)
# If not set, email from your identity provider is used automatically
# Only uncomment this line if you need to use a different email address
# mail: custom.email@example.com

# Reminder timing in days before expiration
# You will receive an email this many days before workspace expires
# Recommended: 3-7 days to give yourself time to extend or backup data
reminder: 5

# Default group name for collaborative workspaces
# If you always work with the same group, set this to avoid typing -G groupname
# Uncomment and set your group name below:
# groupname: bw11a000
</pre>

'''To create this file:'''

$ nano ~/.ws_user.conf

Then paste the configuration above and adjust the values to your needs.

'''Benefits of using ~/.ws_user.conf:'''
* Avoid typing the same options repeatedly
* Ensures consistent settings across all workspace operations
* Simplifies commands: <tt>ws_allocate myWs</tt> instead of <tt>ws_allocate -r 5 myWs 30</tt>
* Automatic group collaboration setup when <tt>groupname</tt> is set

== Cooperative Usage (Group Workspaces and Sharing) ==

When working in teams, workspaces can be shared in multiple ways.

<div style="border: 3px solid red; padding: 15px; background-color: #ffe6e6; margin: 10px 0;">
'''WARNING: NEVER use chmod 777 or a+rwx on workspaces!'''

Do '''NOT''' make your workspace readable or writable by everyone (<tt>chmod 777</tt>, <tt>chmod a+rwx</tt>, or <tt>chmod o+rwx</tt>). This is a severe security risk:
* Anyone on the system can read, modify, or delete your data
* Malicious users can inject code into your workspace
* Your data and results become unreliable
* You violate security policies and may lose access privileges

'''Always use proper sharing methods:''' Use <tt>-g</tt>/<tt>-G</tt> flags, <tt>ws_share</tt>, or group-based permissions instead.
</div>

'''Important:''' Not all sharing methods are available on all clusters. The availability depends on:
* Filesystem type and ACL support
* Cluster-specific workspace tool configuration
* Unix group setup and permissions

If one sharing method doesn't work on your cluster, try an alternative approach. The <tt>-g</tt> and <tt>-G</tt> flags are most widely supported.

=== Group Workspaces ===

{| class="wikitable"
|-
!style="width:40%" | Works on cluster
!style="width:10%" | bwUC 3.0
!style="width:10%" | BinAC2
!style="width:10%" | Helix
!style="width:10%" | JUSTUS 2
!style="width:10%" | NEMO2
|-
|<tt>-g</tt> option (group-readable)
|style="text-align:center;" |
|style="text-align:center;" |
|style="text-align:center;" |
|style="text-align:center;" |
|style="background-color:#90EE90; text-align:center;" | ✓
|-
|<tt>-G</tt> option (group-writable)
|style="text-align:center;" |
|style="text-align:center;" |
|style="text-align:center;" |
|style="text-align:center;" |
|style="background-color:#90EE90; text-align:center;" | ✓
|}

When a workspace is created with <tt>-g</tt> it becomes a group workspace that is visible to others with <tt>ws_list -g</tt> (if in same group), and is group readable:

$ ws_allocate -g myWs 30

When created with <tt>-G <groupname></tt> the workspace becomes writable as well, and gets group sticky bit:

$ ws_allocate -G projectgroup myWs 30

The group can be specified in the <tt>~/.ws_user.conf</tt> file as well.

'''Important:''' Group members can extend group-writable workspaces (created with <tt>-G</tt>) even if the original creator is absent:

$ ws_allocate -x -u <username> <workspace_id> <days>

This requires group write access to the workspace. This is useful when the workspace owner is unavailable and the workspace needs to be extended.

'''Recommendations:'''
* Use <tt>-g</tt> when team members only need to read your results
* Use <tt>-G</tt> for collaborative work where everyone writes data
* Set <tt>groupname</tt> in <tt>~/.ws_user.conf</tt> if you always work with the same group

=== Sharing with ws_share ===

{| class="wikitable"
|-
!style="width:40%" | Works on cluster
!style="width:10%" | bwUC 3.0
!style="width:10%" | BinAC2
!style="width:10%" | Helix
!style="width:10%" | JUSTUS 2
!style="width:10%" | NEMO2
|-
|<tt>ws_share</tt> command (ACL-based)
| style="text-align:center;" |
| style="text-align:center;" |
| style="text-align:center;" |
| style="text-align:center;" |
|style="background-color:#90EE90; text-align:center;" | ✓
|}

With <tt>ws_share</tt> you can share workspaces with users outside your group, using ACLs (if supported by underlying filesystem).

'''Note:''' This feature requires ACL support on the filesystem. If <tt>ws_share</tt> doesn't work on your cluster, use manual ACL commands (<tt>setfacl</tt>) or fall back to Unix group permissions.

'''Share workspace with users:'''

$ ws_share share myWs username1 username2 # Grant read access to one or more users
$ ws_share share -F filesystem myWs user1 # Share on specific filesystem

'''Unshare workspace from users:'''

$ ws_share unshare myWs username1 # Remove access from specific user(s)
$ ws_share unshare-all myWs # Remove access from all users

'''List users with access:'''

$ ws_share list myWs # Show all users with read access

These operations are applied to all files and directories in the workspace.

'''Options:'''
* <tt>-F <filesystem></tt>, <tt>--filesystem</tt>: Specify the workspace filesystem
* <tt>-h</tt>, <tt>--help</tt>: Show help message

'''Recommendation:''' Use <tt>ws_share</tt> for selective sharing with individual users, especially when they are not in your Unix group.

=== ACLs: Access Control Lists ===

{| class="wikitable"
|-
!style="width:40%" | Works on cluster
!style="width:10%" | bwUC 3.0
!style="width:10%" | BinAC2
!style="width:10%" | Helix
!style="width:10%" | JUSTUS 2
!style="width:10%" | NEMO2
|-
|<tt>setfacl</tt>/<tt>getfacl</tt> (ACLs)
| style="text-align:center;" |
| style="text-align:center;" |
| style="text-align:center;" |
| style="text-align:center;" |
|style="background-color:#90EE90; text-align:center;" | ✓
|}

ACLs (Access Control Lists) provide fine-grained permission control beyond standard Unix permissions. They allow sharing with specific users and groups, and support default ACLs that new files automatically inherit.

'''Note:''' ACL support varies by filesystem. Not all clusters support ACLs on workspace filesystems. If ACL commands fail, use regular Unix permissions instead.

'''Key advantages:'''
* Share with specific users (not just groups)
* Default ACLs - new files automatically inherit permissions
* More flexible than Unix permissions

'''Note:''' ACLs take precedence over standard Unix permissions. View ACLs with <tt>ls -l</tt> (shown as "+" after permissions).

==== Quick Examples ====

Set workspace path in variable:

$ DIR=$(ws_find my_workspace)

'''View current ACLs:'''

$ getfacl "$DIR"

'''Important note on syntax:''' In all commands below, <tt>user:</tt> and <tt>group:</tt> are <tt>setfacl</tt> keywords. Replace <tt>username</tt> with the actual user login name (e.g., <tt>alice</tt>, <tt>jdoe</tt>) and <tt>groupname</tt> with the actual Unix group name (e.g., <tt>bw11a000</tt>).

'''Grant read-only access to a user:'''

$ setfacl -Rm user:username:rX,default:user:username:rX "$DIR"
# Example with actual username:
$ setfacl -Rm user:alice:rX,default:user:alice:rX "$DIR"

'''Grant read-write access to a user:'''

$ setfacl -Rm user:username:rwX,default:user:username:rwX "$DIR"
# Example with actual username:
$ setfacl -Rm user:jdoe:rwX,default:user:jdoe:rwX "$DIR"

'''Grant read-only access to a group:'''

$ setfacl -Rm group:groupname:rX,default:group:groupname:rX "$DIR"
# Example with actual groupname:
$ setfacl -Rm group:bw11a000:rX,default:group:bw11a000:rX "$DIR"

'''Remove all ACLs:'''

$ setfacl -Rb "$DIR"

==== Key Options ====

* <tt>-R</tt>: Apply to all files and subdirectories
* <tt>-m</tt>: Modify (add or change ACL entries)
* <tt>-b</tt>: Remove all ACL entries
* <tt>user:username:rwX</tt>: Set permissions for specific user (replace <tt>username</tt> with actual login)
* <tt>group:groupname:rwX</tt>: Set permissions for specific group (replace <tt>groupname</tt> with actual group)
* <tt>default:</tt> prefix: New files inherit these ACLs automatically
* <tt>r</tt>: Read permission
* <tt>w</tt>: Write permission
* <tt>X</tt>: Execute only on directories and already-executable files (capital X)

'''Important:''' Always use the <tt>default:</tt> prefix to ensure new files get the correct permissions automatically.

==== Recommendation ====

'''Always prefer <tt>ws_allocate -G</tt> or <tt>ws_share</tt> first.''' Use manual ACLs only for complex scenarios like:
* Sharing with specific users outside your group
* Different permissions for different users
* Fine-grained control not possible with <tt>-G</tt> or <tt>ws_share</tt>

=== Regular Unix Permissions ===

{| class="wikitable"
|-
!style="width:40%" | Works on cluster
!style="width:10%" | bwUC 3.0
!style="width:10%" | BinAC2
!style="width:10%" | Helix
!style="width:10%" | JUSTUS 2
!style="width:10%" | NEMO2
|-
|<tt>chmod</tt>/<tt>chgrp</tt> (Unix permissions)
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|}

Use standard Unix permissions with <tt>chmod</tt> and <tt>chgrp</tt> when you and your collaborators share a common Unix group.

'''CRITICAL WARNING:'''
* '''NEVER use chmod 777 or a+rwx''' - makes your data accessible to everyone on the system
* '''NEVER use chmod o+rwx or chmod o+w''' - allows anyone to modify or delete your files
* Only set group permissions (<tt>g+r</tt>, <tt>g+w</tt>) for your specific research group

==== Quick Examples ====

Set workspace path in variable:

$ DIR=$(ws_find my_workspace)

'''Read-only access for group:'''

$ chgrp -R mygroup "$DIR"
$ chmod -R g+rX "$DIR"

'''Read-write access for group:'''

$ chgrp -R mygroup "$DIR"
$ chmod -R g+rswX "$DIR"

==== Key Options ====

* <tt>-R</tt>: Apply to all files and subdirectories
* <tt>g+r</tt>: Group read permission
* <tt>g+w</tt>: Group write permission
* <tt>g+x</tt>: Group execute permission
* <tt>X</tt>: Execute only on directories and already-executable files (capital X)
* <tt>s</tt>: Setgid bit (set-group-ID) - new files inherit the directory's group ownership

'''Important:''' The setgid bit (<tt>g+s</tt>) ensures new files belong to the correct group, but their permissions depend on your <tt>umask</tt>. With the default umask (<tt>0022</tt>), new files will NOT be group-writable automatically. You must either:
* Set <tt>umask 0002</tt> in your shell so new files are group-writable by default, OR
* Manually run <tt>chmod g+w</tt> on new files, OR
* Use ACLs with <tt>default:</tt> entries (which override umask and handle permissions automatically)

==== Recommendation ====

'''Always prefer <tt>ws_allocate -G groupname</tt> over manual Unix permissions.''' It handles everything automatically and correctly, including the sticky bit and proper permissions on all new files.

Use manual <tt>chmod</tt>/<tt>chgrp</tt> only when <tt>-G</tt> is not available on your cluster or for fixing permissions on existing data.

== Delete a Workspace ==

{| class="wikitable"
|-
!style="width:40%" | Works on cluster
!style="width:10%" | bwUC 3.0
!style="width:10%" | BinAC2
!style="width:10%" | Helix
!style="width:10%" | JUSTUS 2
!style="width:10%" | NEMO2
|-
|<tt>ws_release --delete-data</tt> (immediate deletion)
|style="background-color:#90EE90; text-align:center;" | ✓
| style="text-align:center;" |
| style="text-align:center;" |
| style="text-align:center;" |
|style="background-color:#90EE90; text-align:center;" | ✓
|}

To release a workspace, use:

$ ws_release myWs

'''Syntax:''' <tt>ws_release [options] workspace_name</tt>

'''What happens when you release:'''
* The workspace ID can be reused
* The directory is not accessible anymore
* The data is '''not deleted immediately''' - it is kept for a grace period
* The data can be recovered using <tt>ws_restore</tt> as long as it is not finally deleted
* The real deletion will probably take place during nighttime

'''Important Notes:'''
* Data in a released workspace can still account for quota usage
* If the data is limiting you, delete the data '''before''' releasing the workspace, or restore it, delete it, and release again
* '''Recommendation:''' If you need to free quota immediately, delete files with <tt>rm -rf</tt> before releasing

=== Options ===

{| class="wikitable"
|-
!style="width:30%" | Option
!style="width:70%" | Description
|-
|<tt>-n <name></tt>
|Workspace name (alternative to positional argument)
|-
|<tt>-F <filesystem></tt>
|Specify filesystem where the workspace is located
|-
|<tt>--delete-data</tt>
|Delete all data immediately. '''WARNING: Workspace can NOT BE RECOVERED'''
|}

=== Immediate Deletion ===

The <tt>--delete-data</tt> flag immediately deletes all data:

$ ws_release --delete-data myWs

'''Warning:''' Deleted data from workspaces is permanently lost and cannot be recovered.

'''When to use:'''
* Use <tt>ws_release</tt> (without flag) when you might need to recover data
* Use <tt>ws_release --delete-data</tt> when you're certain you don't need the data and want to free quota immediately

== Restore an Expired Workspace ==

{| class="wikitable"
|-
!style="width:40%" | Works on cluster
!style="width:10%" | bwUC 3.0
!style="width:10%" | BinAC2
!style="width:10%" | Helix
!style="width:10%" | JUSTUS 2
!style="width:10%" | NEMO2
|-
|<tt>ws_restore</tt>
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|style="background-color:#90EE90; text-align:center;" | ✓
|}

For a certain (system-specific) grace time following workspace expiration, a workspace can be restored.

'''Syntax:''' <tt>ws_restore [options] workspace_name target_name | -l</tt>

=== Restore Procedure ===

'''(1) Display restorable workspaces:'''

$ ws_restore -l

This will list all workspaces that can still be recovered. You can use <tt>-b</tt> or <tt>--brief</tt> to hide the unavailability date in the list.

'''(2) Create a new workspace as the target for the restore:'''

$ ws_allocate restored 60

'''(3) Restore the expired workspace:'''

$ ws_restore <full_name_of_expired_workspace> restored

'''Important:'''
* The expired workspace must be specified using the '''full name''' as printed by <tt>ws_restore -l</tt> (not as printed by <tt>ws_list</tt>!), including username prefix and timestamp suffix (otherwise it cannot be uniquely identified)
* The target workspace must be given with just its '''short name''' as listed by <tt>ws_list</tt>, without the username prefix
* '''<tt>ws_restore</tt> can only work on the same filesystem.''' Ensure the new workspace is on the same filesystem as the expired workspace. Use <tt>-F <filesystem></tt> flag if needed

Example:

$ ws_restore username-myWs-0 restored

=== Options ===

{| class="wikitable"
|-
!style="width:30%" | Option
!style="width:70%" | Description
|-
|<tt>-l</tt>, <tt>--list</tt>
|List restorable workspaces. '''Use this first''' to see what can be recovered
|-
|<tt>-b</tt>, <tt>--brief</tt>
|Do not show unavailability date in list (used with <tt>-l</tt>)
|-
|<tt>-n <name></tt>
|Workspace name (alternative to positional argument)
|-
|<tt>-t <target></tt>
|Existing target workspace name (alternative to positional argument)
|-
|<tt>-F <filesystem></tt>
|Specify filesystem where the workspace is located
|-
|<tt>-u <username></tt>
|Username (for restoring other users' workspaces if permitted)
|}

=== If Workspace Cannot Be Restored ===

If the workspace is not visible/restorable, it has been '''permanently deleted''' and cannot be restored, not even by system administrators.

'''Helix-specific - Workspace Snapshots:'''

On Helix, if the workspace can't be restored anymore using <tt>ws_restore</tt>, you can check the snapshots under:

/work/.snapshots/<timepoint>/ws/

'''Important notes about snapshots:'''
* Snapshots are point-in-time copies of the workspace filesystem
* Changes that happened since the last snapshot was created are lost
* Browse available snapshot timepoints in <tt>/work/.snapshots/</tt>
* '''Caution:''' The Helix team tries to keep the latest snapshots, but they cannot guarantee that snapshots will be available at all times
* Snapshots are a last resort when <tt>ws_restore</tt> no longer works

'''How to use snapshots:'''

$ ls /work/.snapshots/ # List available snapshot timepoints
$ cd /work/.snapshots/2025-11-15_00.00.00/ws/
$ ls # Find your old workspace directory
$ cp -r username-myWs-0 /path/to/active/workspace/ # Copy data to active workspace

Contact Helix support if you need assistance with snapshot recovery.

'''Please remember:''' Workspaces are intended solely for temporary work data, and there is '''no backup''' of data in the workspaces.

'''Recommendation:''' Email reminders are sent automatically. You can optionally customize reminder timing with <tt>-r</tt> option to be notified earlier, giving you time to extend the workspace or backup important data to appropriate permanent storage.

=== Cluster-Specific Information ===

Retention periods for expired/released workspaces vary by cluster:

{| class="wikitable"
|-
!style="width:30%" | Cluster
!style="width:35%" | Expired Workspace Retention
!style="width:35%" | Released Workspace Retention
|-
|bwUniCluster 3.0
|30 days
|Until next night
|-
|Helix
|System-specific grace period
|System-specific grace period
|-
|JUSTUS 2
|System-specific grace period
|System-specific grace period
|-
|BinAC2
|System-specific grace period
|System-specific grace period
|-
|NEMO2
|30 days
|Until next night
|}

== Cluster-Specific Workspace Limits ==

Different clusters have different workspace policies. Below is an overview of typical settings:

{| class="wikitable"
|-
!style="width:15%" | Cluster
!style="width:15%" | Default Lifetime
!style="width:15%" | Max Lifetime
!style="width:15%" | Max Extensions
!style="width:20%" | User Quota
!style="width:20%" | Inode Quota
|-
|bwUniCluster 3.0
|1 day (typical)
|60 days (renewable 3x to 240 days total)
|3 times
|40 TiB
|20 million
|-
|JUSTUS 2
|7 days
|90 days
|Unlimited
|20 TiB
|5 million
|-
|Helix
|N/A
|30 days
|10 times
|10 TiB
|No limit
|-
|BinAC2
|N/A
|30 days
|5 times
|None
|None
|-
|NEMO2
|30 days
|100 days
|100 times
|5 TiB per workspace
|No limit
|}

'''Note:''' Check your specific cluster documentation for current quotas, as they may change. Use <tt>ws_list -l</tt> to see available filesystems and their properties on your cluster.

== Checking Workspace Quotas ==

The command to check workspace quota usage varies by cluster and filesystem:

'''Lustre-based clusters (bwUniCluster 3.0, JUSTUS 2):'''

$ lfs quota -uh $(whoami) /lustre/work # or appropriate workspace path
$ lfs quota -uh $(whoami) /pfs/work9 # bwUniCluster 3.0

'''NEMO2 (Weka filesystem):'''

$ nemoquota # Shows HOME and workspace quotas
$ df --si $(ws_find workspace_name) # Check specific workspace

'''Helix (IBM Spectrum Scale):'''

$ workquotainfo # Shows workspace quota info

'''BinAC2:'''
* No quota limits enforced on workspaces
* Check available space with <tt>df</tt> command

'''General tip:''' Always check disk usage before large data operations to ensure sufficient space is available.

== Register Workspace Links ==

The <tt>ws_register</tt> command creates or updates symbolic links to your workspaces in a directory of your choice. This provides a convenient way to access all your workspaces from a single location.

'''Syntax:''' <tt>ws_register [-h] [--version] [-F FILESYSTEM] directory</tt>

'''Usage:'''

$ ws_register ~/workspaces

This will create symbolic links to all your workspaces in the <tt>~/workspaces</tt> directory.

Example:

$ mkdir -p ~/my_workspaces
$ ws_register ~/my_workspaces
$ ls -l ~/my_workspaces
lrwxrwxrwx 1 user group 45 Nov 17 10:30 myWs -> /work/workspace/scratch/user-myWs-0
lrwxrwxrwx 1 user group 48 Nov 17 10:30 project1 -> /work/workspace/scratch/user-project1-0

=== Options ===

{| class="wikitable"
|-
!style="width:30%" | Option
!style="width:70%" | Description
|-
|<tt>directory</tt>
|Directory in which links shall be created/updated (required positional argument)
|-
|<tt>-F <filesystem></tt>, <tt>--filesystem <filesystem></tt>
|Filesystem to search workspaces in. Only create links for workspaces on this filesystem
|-
|<tt>-h</tt>, <tt>--help</tt>
|Show help message
|-
|<tt>--version</tt>
|Show program's version number and exit
|}

'''When to use:'''
* '''Recommended''' if you work with multiple workspaces and want quick access
* Use in your <tt>~/.bashrc</tt> or login scripts to automatically update links at login
* Useful for organizing workspaces by project or purpose

'''Example in login script:'''

<pre>
# In ~/.bashrc
if command -v ws_register &> /dev/null; then
mkdir -p ~/workspaces
ws_register ~/workspaces 2>/dev/null
fi
</pre>

Latest revision as of 17:43, 2 December 2025

This document covers advanced features and detailed configuration options for the HPC workspace tools. For basic daily usage, see the main Workspaces guide.

Almost Complete Command Reference

Task Command
Create workspace for 30 days ws_allocate myWs 30
Create with custom email ws_allocate -m custom@example.com -r 3 myWs 30
Create group-writable workspace ws_allocate -G groupname myWs 30
Create on specific filesystem ws_allocate -F filesystem myWs 30
List all your workspaces ws_list
List by remaining time ws_list -R
List available filesystems ws_list -l or ws_find -l
Find workspace path ws_find myWs
Extend workspace by 40 days ws_extend myWs 40 or ws_allocate -x myWs 40
Share with another user ws_share share myWs username
List shared users ws_share list myWs
Send calendar reminder ws_send_ical myWs user@example.com
Release workspace ws_release myWs
List restorable workspaces ws_restore -l
Register workspace links ws_register ~/workspaces

Detailed Topics

Commands

  • ws_allocate - Create and extend workspaces (detailed options)
  • ws_list - List workspaces (sorting, filtering)
  • ws_find - Find workspace paths for scripts
  • ws_extend - Extend workspace lifetime
  • ws_release - Release (delete) workspaces with immediate deletion options
  • ws_restore - Restore expired or released workspaces
  • ws_register - Create symbolic links to workspaces

Configuration & Features

Best Practices

Quick Navigation

By Task

Creating and Managing:

Collaboration:

Configuration:

Resources:

By Experience Level

Beginners:

Intermediate Users:

Advanced Users:

Retrieved from "https://wiki.bwhpc.de/wiki/index.php?title=Workspaces/Advanced_Features&oldid=15614"