Fetaure/file systems

docs/data/layout.md

@@ -1,16 +1,16 @@
-# Global Directory Structure
+# Cluster file systems
+
+Several _network file systems_ are available at the UL HPC clusters and are configured for different purposes. Each server and computational resources has access to at least three different file systems with different levels of performance, permanence, and available space. This is a high level description of  the data management practices for our file systems. You can find information about performance and best usage practices in the [Storage Systems](/filesystems/) section.
 
 {%
    include-markdown "../filesystems/overview.md"
 %}
 
-
 {%
    include-markdown "../filesystems/home.md"
    end="<!--intro-end-->"
 %}
 
-
 {%
    include-markdown "../filesystems/projecthome.md"
    end="<!--intro-end-->"
@@ -21,7 +21,7 @@
    end="<!--intro-end-->"
 %}
 
-## Project Cold-Data and Archives
+## Cold project data and archives
 {%
    include-markdown "../filesystems/isilon.md"
    start="<!--intro-start-->"

docs/filesystems/home.md

@@ -1,8 +1,9 @@
-## Global Home directory `$HOME`
+## Home directory (`${HOME}`)
 
 Home directories provide a convenient means for a user to have access to files such as dotfiles, source files, input files, configuration files regardless of the platform.
 
-Refer to your home directory using the environment variable `$HOME` whenever possible.
-The absolute path may change, but the value of `$HOME` will always be correct.
+Use your home directory to store working data, that are actively accessed by multiple processes in your computations. Home directories are cached, so small files and random I/O is relatively fast but not as fast as local storage. The file system is redundant so it is safe to data and access loss due to hardware failure. _Redundancy does not replace backups, so do not leave your data stored in your home._
+
+Refer to your home directory using the environment variable `${HOME}` whenever possible. The absolute path may change, but the value of `${HOME}` will always be correct.
 
 <!--intro-end-->

docs/filesystems/isilon.md

@@ -1,8 +1,21 @@
-# Dell EMC Isilon (Archives and cold project data)
+# Dell EMC Isilon (Cold project data and Archives)
 
 <!--intro-start-->
 
-OneFS, A global _low_-performance [Dell/EMC Isilon](https://www.dellemc.com/en-us/collaterals/unauth/data-sheets/products/storage/h10717-isilon-onefs-ds.pdf) solution is used to host project data, and serve for backup and archival purposes. You will find them mounted under `/mnt/isilon/projects`.
+The university _central data storage services_ uses a [NAS](https://en.wikipedia.org/wiki/Network-attached_storage) system to provide long term storage for user data. The NAS system used is a [Dell/EMC Isilon](https://www.dellemc.com/en-us/collaterals/unauth/data-sheets/products/storage/h10717-isilon-onefs-ds.pdf) (Isilon) server with [OneFS](https://en.wikipedia.org/wiki/OneFS_distributed_file_system), a proprietary and distributed file system and environment, used to store the data. The OneFS file systems is exported by Isilon through the NFS protocol to the HPC platform and other Linux-based services, and through SMB (CIFS) to Windows-based clients.
+
+In the UL HPC platform the NFS exported by Isilon is used to host project data when they are not activelly used in computations, and for archival purposes. Projects are mounted under `/mnt/isilon/projects`.
+
+-  The file system in Isilon is redundant and regularly snapshot and backed up, including off site backups. It thus resilient to hardware failure and highly available, but it is also protected against catastrophic data loss.
+
+- The NFS share exported from Isilon to the UL HPC platform is not using the Infiniband high performance network and the OneFS file system has lower I/O performance that GPFS and lustre file systems, however, the central data storage has significantly higher capacity.
+
+!!! important "Long term data storage"
+    Please move all your data to OneFS directories of the central data storage as soon as your computations finish.
+
+    The central data storage is the intended place for storing data. Cluster file systems using the inifiniband network are meant as working storage only. For this reason, backups in cluster file systems are very limited.
+
+Users have to ask for a project directories in the Isilon mount point (`/mnt/isilon/projects`) separately from the GPFS project directories. However, all users have a personal directory in the university _central data storage_ which they can access through the [ATLAS SMB system](https://hpc-docs.uni.lu/data/transfer/#transfers-between-long-term-storage-and-the-hpc-facilities). Users may also ask for project directories that are accessible through ATLAS, however these project cannot be mounted on the Isilon NFS share (`/mnt/isilon/projects`).
 
 <!--intro-end-->
 

docs/filesystems/overview.md

@@ -1,15 +1,23 @@
-## ULHPC File Systems Overview
+## ULHPC File system overview
 
 <!--content-start-->
 
-Several _File Systems_ co-exist on the ULHPC facility and are configured for different purposes.
-Each servers and computational resources has access to at least three different file systems with different levels of performance, permanence and available space summarized below
+The following table summarizes the mount location, backing up, and environment setup for each one of the network file systems.
 
 <!--table-start-->
 
-| Directory                                                                                            | Env.                                                         | file system                                  | backup                               |
-|------------------------------------------------------------------------------------------------------|--------------------------------------------------------------|----------------------------------------------|--------------------------------------|
-| [`/home/users/<login>`](../filesystems/gpfs.md#global-home-directory-home)                           | [`$HOME`](../filesystems/gpfs.md#global-home-directory-home) | [GPFS/Spectrumscale](../filesystems/gpfs.md) | no                                   |
-| [`/work/projects/`](../filesystems/gpfs.md#global-project-directory-projecthomeworkprojects)`<name>` | -                                                            | [GPFS/Spectrumscale](../filesystems/gpfs.md) | yes (partial, `backup` subdirectory) |
-| [`/scratch/users/<login>`](../filesystems/lustre.md)                                                 | [`$SCRATCH`](../filesystems/lustre.md)                       | [Lustre](../filesystems/lustre.md)           | no                                   |
-| `/mnt/isilon/projects/<name>`                                                                        | -                                                            | [OneFS](../filesystems/isilon.md)            | yes (live sync and snapshots)        |
+!!! info "Cluster file systems"
+
+    | Directory                                                                                                  | Environment variable                                           | File system                                      | Backup                                    |
+    |------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------|--------------------------------------------------|-------------------------------------------|
+    | [`/home/users/<username>`](../filesystems/gpfs.md#global-home-directory-home)                              | [`${HOME}`](../filesystems/gpfs.md#global-home-directory-home) | [GPFS/Spectrumscale](../filesystems/gpfs.md) [1] | no                                        |
+    | [`/work/projects/<project name>`](../filesystems/gpfs.md#global-project-directory-projecthomeworkprojects) | -                                                              | [GPFS/Spectrumscale](../filesystems/gpfs.md) [1] | yes (partial, only `backup` subdirectory) |
+    | [`/scratch/users/<username>`](../filesystems/lustre.md)                                                    | [`${SCRATCH}`](../filesystems/lustre.md)                       | [Lustre](../filesystems/lustre.md)               | no                                        |
+    | `/mnt/isilon/projects/<project name>`                                                                      | -                                                              | [OneFS](../filesystems/isilon.md)                | yes (and live sync [2])                   |
+
+    1. The  file system mounted on the home directories (`/home/users`) and project directories (`/work/projects`) are both exported by the [GPFS/Spectrumscale](../filesystems/gpfs.md) file system.
+
+        - Storage for both directories is redundant, so they are safe against hardware failure.
+        - Only `/home/users` is mirrored in a SSD cache, so `/home/users` is a significantly faster for random and small file I/O.
+
+    2. Live sync replicates data across multiple OneFS instances for high availability.

docs/filesystems/projecthome.md

@@ -1,7 +1,9 @@
-## Global Project directory `$PROJECTHOME=/work/projects/`
+## Project directories `(${PROJECTHOME})`
 
-Project directories are intended for sharing data within a group of researchers, under `/work/projects/<name>`
+Project directories are intended for sharing data within a group of researchers, and are stored under the path `/work/projects/<project name>`. Project directories are also accessible from every node in the cluster.
 
-Refer to your project _base_ home directory using the environment variable `$PROJECTHOME=/work/projects` whenever possible.
+Use project directories to store input and output data for your jobs. Data can be accessed by multiple processes in your computation. Project directories are not cached so small file I/O performance is lower that the home directory. The file system is redundant so it is safe to data and access loss due to hardware failure. _Redundancy does not replace backups, so do not leave your data stored in your project directories._
+
+The parent directory of all project directories (`/work/projects`) can be referenced using the environment variable `${PROJECTHOME}`. Use `${PROJECTHOME}` whenever possible as it is guaranteed to point to the parent directory of all project directories.
 
 <!--intro-end-->

docs/filesystems/scratch.md

@@ -1,11 +1,15 @@
-## Global Scratch directory `$SCRATCH`
+## Scratch directory `(${SCRATCH})`
 
 The _scratch_ area is a [Lustre](http://lustre.org/)-based file system designed for high performance temporary storage of large files.
 
-It is thus intended to support large I/O for jobs that are being actively computed on the ULHPC systems.
-We recommend that you run your jobs, especially data intensive ones, from the ULHPC scratch file system.
+The scratch is used to write large files in a continuous manner. The term originates from [scratch data tapes](https://en.wikipedia.org/wiki/Scratch_tape). People uses scratch tapes to write and read data that did not fit into the main memory, and since it was a tape, it could only perform continuous I/O. The term scratch is a bit abused in modern times as most storage systems nowadays support random access. In the case of the UL HPC scratch however, we use the term literally. Our file system in scratch has a very bad performance in small file and random reads and writes.
 
-Refer to your scratch directory using the environment variable `$SCRATCH` whenever possible (which expands to `/scratch/users/$(whoami)`).
-The scratch file system is shared via the Infiniband network of the ULHPC facility and is available from all nodes while being tuned for high performance.
+_If you cannot guarantee that your computations will read and write the data in a continuous manner and in large files then do not use the scratch._
+
+The scratch is intended to support large file continuous I/O for jobs that are being actively computed on the UL HPC systems. If you are sure about the data access pattern of your job, the we recommend that you run the I/O of your jobs, especially data intensive ones, from the UL HPC scratch file system.
+
+The file system is redundant so it is safe to data and access loss due to hardware failure. _Redundancy does not replace backups, so do not leave your data stored in your scratch directory._
+
+Refer to your scratch directory using the environment variable `${SCRATCH}` whenever possible (which expands to `/scratch/users/$(whoami)`). The scratch file system is shared via the Infiniband network of the ULHPC facility and is available from all nodes while being tuned for high performance.
 
 <!--intro-end-->

mkdocs.yml

@@ -55,7 +55,7 @@ nav:
     # - Multi-Factor Authentication: 'connect/mfa.md'
   ##################
   - Data Management:
-    - Global Directory Structure: 'data/layout.md'
+    - Cluster file systems:       'data/layout.md'
     - Data Sharing:               'data/sharing.md'
     - Data Transfer:              'data/transfer.md'
     - GDPR Compliance:            'data/gdpr.md'