[GNUnet-SVN] r30208 - msh/doc

[gnunet]

Author: harsha
Date: 2013-10-16 11:27:52 +0200 (Wed, 16 Oct 2013)
New Revision: 30208

Modified:
   msh/doc/msh.tex
Log:
- doc: supermuc interactive mshd launch and termination


Modified: msh/doc/msh.tex
===================================================================
--- msh/doc/msh.tex     2013-10-16 08:34:37 UTC (rev 30207)
+++ msh/doc/msh.tex     2013-10-16 09:27:52 UTC (rev 30208)
@@ -190,11 +190,11 @@
 addresses for an instance.
 
 \section{Limitations}
-MSH does not have terminal handling capabilities.  This means that applications
-such as \texttt{screen}, \texttt{less}, \texttt{vim} which require terminal
-(\texttt{tty}) support do not work through MSH.  This also means that there is
-no support for sending control character sequences such as \texttt{Control+C} 
to
-the remote command.
+MSH does not have terminal handling capabilities yet.  This means that
+applications such as \texttt{screen}, \texttt{less}, \texttt{vim} which require
+terminal (\texttt{tty}) support do not work through MSH.  This also means that
+there is no support for sending control character sequences such as
+\texttt{Control+C} to the remote command.
 
 \cleardoublepage
 \chapter{User Guide}
@@ -259,9 +259,22 @@
 execution wrapper to run 1 MPI process per node.  When the allocation is
 successful, \texttt{mshd} is launched in line 2 with the command
 \texttt{srun\_ps} which is specific to SLURM for launching MPI programs.  When
-MSH is launched successfully, the first \texttt{mshd} process will start
+MSH is launched successfully, the root \texttt{mshd} process will start
 \texttt{bash}.
 
+\begin{lstlisting}[language=bash, caption=Starting MSH as an interactive job 
using
+  LoadLeveler, label=lst:ll_interactive, numbers=left]
+$ export MP_NODES=3
+$ export MP_TASKS_PER_NODE=1
+$ poe mshd -- /bin/bash
+\end{lstlisting} %$
+
+Listing~\ref{lst:ll_interactive} shows interactive MSH startup on SuperMUC 
using
+the LoadLeveler scheduler.  In lines 1, 2 we specify that we want to allocate 3
+nodes for our experiment and only one instance of \texttt{mshd} has to be
+started on each of them.  In line 3, we start \texttt{mshd} processes through
+the LoadLeveler's \texttt{poe} command.
+
 \section{Using MSH}
 \label{sec:using}
 
@@ -275,7 +288,8 @@
 available through the environmental variable \texttt{MP\_SAVEHOSTFILE}.
 \texttt{msh} can be used to connect to any of the hosts listed in this file.
 Listing~\ref{lst:msh_connect} shows an example for connecting to the allocated
-hosts.
+hosts.  The commands are executed in a \texttt{bash} process started by the 
root
+\texttt{mshd} instance (run from the line 2 in 
Listing~\ref{lst:slurm_interactive}).
 
 \begin{lstlisting}[language=bash, caption=Using \texttt{msh} to connect to
   remote hosts.  The commands are run in a \texttt{bash} process started 
through
@@ -304,19 +318,45 @@
 network experiments which rely on SSH for starting remote processes can use MSH
 as a replacement for SSH.
 
-\begin{lstlisting}[label=slurm_interactive_testbed_startup, caption=Commands to
-  start a testbed program which uses MSH]
+\begin{lstlisting}[language=bash, label=slurm_interactive_testbed_startup,
+  caption=Commands to start a testbed program which uses MSH]
 $ salloc --ntasks-per-node=1 -N 3 -p mpp1_inter
 $ srun_ps mshd -- ./gnunet-testbed-profiler \
     -c ../../contrib/testbed_infiniband.conf -p 1000 -e 5
 \end{lstlisting}
 
+On a system with LoadLeveler such as SuperMUC the above experiment startup is
+shown in Listing~\ref{lst:ll_interactive_testbed_startup}
+
+\begin{lstlisting}[language=bash, label=ll_interactive_testbed_startup,
+  caption=Commands to start testbed program which uses MSH with LoadLeveler
+  scheduler]
+$ export MP_NODES=3
+$ export MP_TASKS_PER_NODE=1
+$ poe mshd -- ./gnunet-testbed-profiler \
+    -c ../../contrib/testbed_infiniband.conf -p 1000 -e 5
+\end{lstlisting} %$
+
 \section{Termination}
 \label{sec:termination}
 
-Termination in MSH happens when the process launched by the root \texttt{mshd}
-instance is terminated.
+Termination in MSH can be divided into two parts: the termination of remote
+access connections started through \texttt{msh} processes and the termination 
of
+\texttt{mshd} processes.
 
+\texttt{msh} processes terminate successfully when the remote command execution
+is complete and all the output from the command is fetched from the remote
+host.  They terminate with error if the remote connection is broken, remote
+\texttt{mshd} process crashes or remote host goes down, if the given command is
+not found on the remote host and if the local \texttt{msh} processes receives
+any of the termination (SIGTERM, SIGINT) signals.
+
+The \texttt{mshd} processes terminate successfully when the main process 
started
+by the root \texttt{mshd} processes terminates.  They terminate with error if
+the main process crashes or terminates with error, or if the binary needed for
+launching the main process is not found, or upon a crash of any of the
+\texttt{mshd} processes.
+
 \cleardoublepage
 \printbibliography