add new feature docs

Signed-off-by: jason yang <[email protected]>

mpi.rst

@@ -245,6 +245,8 @@ If the host MPI is Open MPI, the definition file looks like:
    Consult your system documentation, or ask your support staff for
    details.
 
+
+.. _mpi-issue:
 .. note::
 
    The MPI UCX library has a problem with unprivileged user namespaces.
@@ -257,6 +259,24 @@ If the host MPI is Open MPI, the definition file looks like:
 
       mpirun -np 2 -mca pml ucx -x UCX_TLS=sysv,ib apptainer exec $MY_CONTAINER ./a.out
 
+Using --sharens mode
+====================
+
+Default in unprivileged user namespace mode. Each process spawned by MPI runs in its own user namespace. This will 
+bring problems as observed :ref:`in this issue <mpi-issue>`. The new ``--sharens`` flag will 
+move all spawned processes into the same user namespace, similar to what is done with {Project} SUID mode. 
+
+.. code::
+
+   mpirun -np 2 apptainer exec --sharens $MY_CONTAINER ./a.out
+
+.. note::
+
+   Note that ``--sharens`` flag requires all spawned processes having the same parent process. This is because these
+   child processes will join the same namespace identified using the parent process id. To meet the requirement, {Project} 
+   containers should be launched by the same process, e.g. mpirun, and all these containers should be running on the same host. 
+   ``--sharens`` does not support sharing the same namespace accross different hosts.
+
 Running an MPI Application
 ==========================