[GNUnet-SVN] r29070 - msh/doc

[gnunet]

Author: harsha
Date: 2013-09-06 14:37:42 +0200 (Fri, 06 Sep 2013)
New Revision: 29070

Modified:
   msh/doc/
   msh/doc/msh.tex
   msh/doc/related_work.bib
Log:
- doc user guide


Index: msh/doc
===================================================================
--- msh/doc     2013-09-06 12:13:03 UTC (rev 29069)
+++ msh/doc     2013-09-06 12:37:42 UTC (rev 29070)

Property changes on: msh/doc
___________________________________________________________________
Modified: svn:ignore
## -4,3 +4,9 ##
 msh.out
 msh.pdf
 msh.aux
+msh-blx.bib
+msh.lof
+msh.toc
+msh.bbl
+msh.run.xml
+msh.blg
Modified: msh/doc/msh.tex
===================================================================
--- msh/doc/msh.tex     2013-09-06 12:13:03 UTC (rev 29069)
+++ msh/doc/msh.tex     2013-09-06 12:37:42 UTC (rev 29070)
@@ -1,19 +1,42 @@
-\documentclass[10pt, a4paper, onecolumn, twosided]{article}
+\documentclass[10pt, a4paper, onecolumn, oneside]{scrreprt}
 
 \usepackage[utf8]{inputenc}
 \usepackage{color}
 \usepackage{graphicx}
 \usepackage{import}
 \usepackage[pdftex,hyperfootnotes=false,pdfpagelabels]{hyperref}
+\usepackage{listings}
+\usepackage[sorting=none]{biblatex}
+%\usepackage{courier}
 
 \graphicspath{{fig/svg/}}
+\bibliography{related_work}
 
+
 \title{MSH: A remote shell based on MPI}
 \author{Sree Harsha Totakura}
+\lstset{language=bash,
+  basicstyle=\small\ttfamily,
+  numbers=left,
+  numberstyle=\tiny,
+  frame=b,
+  columns=fullflexible,
+  showstringspaces=false,
+  captionpos=b
+}
 
+\newcommand\todo[1]{
+  \marginpar{\textcolor{red}{TBD:} #1}
+  \PackageWarning{TODO:}{ #1}
+}
+
 \begin{document}
-\maketitle{}
-
+\maketitle
+\cleardoublepage
+\tableofcontents
+\cleardoublepage
+\listoffigures
+\cleardoublepage
 \begin{abstract}
   MPI-Shell (MSH) is a remote shell for executing commands remotely on hosts
   where Message Passing Interface (MPI) layer is available for communication.
@@ -29,6 +52,8 @@
   instead of SSH.
 \end{abstract}
 
+\cleardoublepage
+\chapter{Technical Documentation}
 
 \section{Introduction}
 Large scale network experimentation of distributed systems is achieved by
@@ -151,7 +176,7 @@
 each of the sender's IP addresses.  The TCP connections are started in parallel
 and in non-blocking mode.  This is depicted in Figure~\ref{fig:ip_map}.
 
-\begin{figure}[h]
+\begin{figure}[ht]
   \centering
   \input{fig/svg/ip_map.pdf_tex}
   \caption{Instances verifying IP addresses during $i^{th}$ round}
@@ -171,7 +196,128 @@
 no support for sending control character sequences such as \texttt{Control+C} 
to
 the remote command.
 
-\bibliographystyle{plain}
-\bibliography{related_work}
+\cleardoublepage
+\chapter{User Guide}
+This chapter provides information for the installation of MSH and its usage.  
We
+provide examples which showcase how MSH is used in experiments conducted on HPC
+systems.
 
+\section{Installation}
+MSH depends on GNUnet's networking API and hence requires gnunet-0.9.5a to be
+installed.  Additionally, it requires an MPI implementation to be installed
+together with the MPI compiler wrapper \texttt{mpicc}.
+
+Once the dependencies are installed, MSH can be installed by running the
+following in the MSH source directory:
+{\small
+\begin{verbatim}
+$ ./configure
+$ make
+$ make install
+\end{verbatim} %$
+}
+If the required dependencies are not in the default search paths of the
+compiler, \texttt{configure} may fail complaining an error.  These can be fixed
+by providing the installation directories of the dependencies to
+\texttt{configure}.  For a list of available options type:
+{\small
+\begin{verbatim}
+$ ./configure --help
+\end{verbatim}%$
+}
+
+
+\section{Starting MSH}
+MSH is started by running the MSH daemon on the available nodes through the MPI
+execution wrappers.  The available nodes are determined either manually and
+given to the execution wrapper as a hostlist file (as in the case with small
+group of systems or clusters) or dynamically by either a job scheduling system
+such as LoadLeveler\cite{prenneis1996loadleveler} or SLURM\cite{yoo2003slurm}.
+The execution wrappers can be started as an interactive job or as a batch job.
+Interactive job execution gives more control to the user as the user can
+directly interact with the job through the job's standard input and output.
+Batch job execution allows for the job to be queued in a batch scheduling 
system
+which executes the job whenever the required number of resources are available.
+
+Since only one MSH daemon should run on each host, the wrappers are configured
+with the respective parameters such that they start only one instance of MSH 
per
+host.
+
+Examples for starting MSH on various HPC systems are shown in the following
+listings. \todo{Need more examples}
+
+\begin{lstlisting}[language=bash, caption=Starting MSH as an interactive job on
+  a cluster with SLURM job manager, label=lst:slurm_interactive, numbers=left]
+$ salloc --ntasks-per-node=1 -N 3 -p mpp1_inter
+$ srun_ps mshd -- /bin/bash
+\end{lstlisting}
+
+Listing~\ref{lst:slurm_interactive} shows interactive MSH startup on an MPI
+cluster.  The cluster uses SLURM for job scheduling.  The command
+\texttt{salloc} in line 1 is used to allocate resources.  Here we allocate 3
+nodes from the cluster partition \texttt{mpp1\_inter} and configure the MPI
+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
+\texttt{bash}.
+
+\section{Using MSH}
+\label{sec:using}
+
+The usage of MSH is aimed at HPC systems where remote shells are disabled and
+MPI is available.  With MSH, we address two problems: 1. we facilitate remote
+command execution and 2. we provide an easy interface to learn which hosts are
+allocated to the job by listing their addresses.
+
+The IP addresses of the hosts are made available as hostlist file to the
+processes \texttt{mshd} processes start.  The path of this hostlist file is 
made
+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.
+
+\begin{lstlisting}[language=bash, caption=Using \texttt{msh} to connect to
+  remote hosts.  The commands are run in a \texttt{bash} process started 
through
+  MSH in a cluster, label=lst:msh_connect]
+$ cat $MP_SAVEHOSTFILE
+10.0.0.3
+10.0.0.4
+10.0.0.5
+$ msh 10.0.0.4 date
+Fri Sep  6 11:17:09 CEST 2013
+$ quit
+\end{lstlisting}
+
+MSH can also be used by programs which are started by \texttt{mshd} instances.
+The programs however should take care to read the addresses of allocated hosts
+from the hostlist file from the evironmental variable and use \texttt{msh} for
+executing remote commands on those hosts.
+
+In our experiments, our distributed testbed~\cite{totakura2013ms} determines 
the
+allocated hosts through the hostfile and uses \texttt{msh} to spawn controllers
+for each allocated host.  The start-up of the testbed is initiated from the 
root
+\texttt{mshd} instance which starts a master controller on the host where the
+root \texttt{mshd} instance is running.
+Listing~\ref{slurm_interactive_testbed_startup} shows the commands used to 
start
+the testbed.  In the same way, other simulation and emulation software for
+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]
+$ 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}
+
+\section{Termination}
+\label{sec:termination}
+
+Termination in MSH happens when the process launched by the root \texttt{mshd}
+instance is terminated.
+
+\cleardoublepage
+\printbibliography
+
 \end{document}

Modified: msh/doc/related_work.bib
===================================================================
--- msh/doc/related_work.bib    2013-09-06 12:13:03 UTC (rev 29069)
+++ msh/doc/related_work.bib    2013-09-06 12:37:42 UTC (rev 29070)
@@ -2,7 +2,7 @@
        title = {Large Scale Distributed Evaluation of Peer-to-Peer Protocols},
        volume = {Master of Science},
        year = {2013},
-       month = {06/2013},
+       month = {6},
        pages = {76},
        school = {Technische Universit\"at M\"unchen},
        type = {Masters },
@@ -18,6 +18,25 @@
        author = {Totakura, Sree Harsha}
 }
 
address@hidden,
+  title={SLURM: Simple linux utility for resource management},
+  author={Yoo, Andy B and Jette, Morris A and Grondona, Mark},
+  booktitle={Job Scheduling Strategies for Parallel Processing},
+  pages={44--60},
+  year={2003},
+  organization={Springer}
+}
+
address@hidden,
+  title={Loadleveler: Workload management for parallel and distributed 
computing environments},
+  author={Prenneis Jr, A},
+  journal={Proceedings of Supercomputing Europe (SUPEUR)},
+  volume={176},
+  year={1996}
+}
+
+
+
 @INPROCEEDINGS{DBLP:conf/tridentcom/AlbrechtH10,
   author = {Jeannie R. Albrecht and Danny Yuxing Huang},
   title = {Managing Distributed Applications Using Gush},