doc/user_manual/getting_started.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %
   3 %    NEPI, a framework to manage network experiments
   4 %    Copyright (C) 2013 INRIA
   5 %
   6 %    This program is free software: you can redistribute it and/or modify
   7 %    it under the terms of the GNU General Public License as published by
   8 %    the Free Software Foundation, either version 3 of the License, or
   9 %    (at your option) any later version.
  10 %
  11 %    This program is distributed in the hope that it will be useful,
  12 %    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 %    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 %    GNU General Public License for more details.
  15 %
  16 %    You should have received a copy of the GNU General Public License
  17 %    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18 %
  19 % Author: Alina Quereilhac <alina.quereilhac@inria.fr>
  20 %
  21 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  22
  23 NEPI is written in Python, so you will need to install Python before
  24 being able to run experiments with NEPI.
  25 NEPI is known to work on Linux (Fedore, Debian, Ubuntu) and Mac (OS X).
  26
  27 \section{Dependencies}
  28
  29 Dependencies for NEPI vary according to the features you want to enable.
  30 Make sure the following dependencies are correctly installed in your system
  31 before using NEPI. \\
  32
  33 Mandatory dependencies:
  34 \begin{itemize}
  35     \item Python 2.6+
  36     \item Mercurial
  37 \end{itemize}
  38
  39 Optional dependencies:
  40 \begin{itemize}
  41     \item SleekXMPP - Required to run experiments on OMF testbeds
  42 \end{itemize}
  43
  44 \subsection{Install dependencies on Debian/Ubuntu}
  45
  46 \begingroup
  47     \fontsize{10pt}{12pt}\selectfont
  48
  49 \begin{verbatim}
  50     $ sudo aptitude install -y python mercurial
  51 \end{verbatim}
  52
  53 \endgroup
  54
  55 \subsection{Install dependencies on Fedora}
  56
  57 \begingroup
  58     \fontsize{10pt}{12pt}\selectfont
  59
  60 \begin{verbatim}
  61     $ sudo yum install -y python mercurial
  62 \end{verbatim}
  63
  64 \endgroup
  65
  66 \subsection{Install dependencies on Mac}
  67
  68 First install homebrew (\url{http://mxcl.github.io/homebrew/}),
  69 then install Python.
  70
  71 \begingroup
  72     \fontsize{10pt}{12pt}\selectfont
  73
  74 \begin{verbatim}
  75     $ brew install python
  76 \end{verbatim}
  77
  78 \endgroup
  79
  80 \subsection{Install SleekXMPP}
  81
  82 You will need \textit{git} to get the SleekXMPP sources.
  83
  84 \begingroup
  85     \fontsize{10pt}{12pt}\selectfont
  86
  87 \begin{verbatim}
  88     $ git clone -b develop git://github.com/fritzy/SleekXMPP.git
  89     $ cd SleekXMPP
  90     $ sudo python setup.py install
  91 \end{verbatim}
  92
  93 \endgroup
  94
  95 \section{The source code}
  96
  97 To get NEPI's source code you will need Mercurial version
  98 control system. The Mercurial NEPI repo can also be browsed online at: \\
  99
 100 \url{http://nepi.inria.fr/code/nepi/}
 101
 102 \subsection{Clone the repo}
 103
 104 \begingroup
 105     \fontsize{10pt}{12pt}\selectfont
 106
 107 \begin{verbatim}
 108 $ hg clone http://nepi.inria.fr/code/nepi -r nepi-3.0-release
 109 \end{verbatim}
 110
 111 \endgroup
 112
 113 \section{Install NEPI in your system}
 114
 115 You don't need to install NEPI in your system to be able to run
 116 experiments. However this might be convenient if you don't
 117 plan to modify or extend the sources.
 118
 119 To install NEPI, just run \emph{make install} in the NEPI source
 120 folder.
 121
 122 \begingroup
 123     \fontsize{10pt}{12pt}\selectfont
 124
 125 \begin{verbatim}
 126     $ cd nepi
 127     $ make install
 128 \end{verbatim}
 129
 130 \endgroup
 131
 132 If you are developing your own NEPI extensions, the installed
 133 NEPI version might interfere with your work.
 134 In this case it is probably more convenient to tell
 135 Python where to find the NEPI sources, using the PYTHONPATH
 136 environmental variable, when you run a NEPI script.
 137
 138 \begingroup
 139     \fontsize{10pt}{12pt}\selectfont
 140
 141 \begin{verbatim}
 142     $ PYTHONPATH=$PYTHONPATH:<path-to-nepi>/src python experiment.py
 143 \end{verbatim}
 144
 145 \endgroup
 146
 147 \section{Run experiments}
 148
 149 There are two ways you can use NEPI to run your experiments.
 150 The first one is writing a Python script, which will import
 151 NEPI libraries, and run it.
 152 The second one is in interactive mode by using Python console.
 153
 154 \subsection{Run from script}
 155
 156 Writing a simple NEPI expeiment script is easy.
 157 Take a look at the example in the FAQ section \ref{faq:ping_example}.
 158 Once you have written down the script, you can run it using
 159 Python. Note that since NEPI is not yet installed in your system,
 160 you will need to export the path to NEPI's source code to
 161 the PYTHONPATH environment variable, so that Python can find
 162 NEPI's libraries.
 163
 164 \begingroup
 165     \fontsize{10pt}{12pt}\selectfont
 166
 167 \begin{verbatim}
 168     $ export PYTHONPATH=<path-to-nepi>/src:$PYTHONPATH
 169     $ python first-experiment.py
 170 \end{verbatim}
 171
 172 \endgroup
 173
 174 \subsection{Run interactively}
 175
 176 The Python interpreter can be used as an interactive console to execute
 177 Python instructions.
 178 We can take advantage of this feature, to interactively run experiments
 179 with NEPI. We  use the \textit{ipython} console for the example below,
 180 you can install it with \textit{sudo yum/aptitude install ipython} on
 181 Fedora/Debian.
 182
 183 \begingroup
 184     \fontsize{10pt}{12pt}\selectfont
 185
 186 \begin{verbatim}
 187 $ export PYTHONPATH=<path-to-nepi>/src:$PYTHONPATH
 188 $ ipython
 189 Python 2.7.3 (default, Jan  2 2013, 13:56:14)
 190 Type "copyright", "credits" or "license" for more information.
 191
 192 IPython 0.13.1 -- An enhanced Interactive Python.
 193 ?         -> Introduction and overview of IPython's features.
 194 %quickref -> Quick reference.
 195 help      -> Python's own help system.
 196 object?   -> Details about 'object', use 'object??' for extra details.
 197
 198 \end{verbatim}
 199
 200 \endgroup
 201
 202 With ipython, if you want to paste many lines at once you will need to type
 203 \emph{\%cpaste} and finish the paste block with \emph{\-\-}.
 204
 205 The first thing we have to do is to import the NEPI classes
 206 we will use.
 207 In particular we need to import the ExperimentController class.
 208
 209 \begin{lstlisting}[language=Python]
 210
 211 from nepi.execution.ec import ExperimentController
 212
 213 \end{lstlisting}
 214
 215 Then we need to create an ExperimentController instance.
 216 The \textit{exp-id} argument serves as a human readable identifier
 217 for the experiment to be ran.
 218
 219 \begin{lstlisting}[language=Python]
 220
 221 ec = ExperimentController(exp_id = "<your-exp-id>")
 222
 223 \end{lstlisting}
 224
 225 Next we will define two Python functions, one to register \emph{LinuxNode}
 226 resources and the other to register \emph{LinuxApplication} resources.
 227 A \emph{LinuxNode} resource (or ResourceManager) will serve as an abstraction
 228 to a Linux host resource, that can be accessed using SSH key authentication.
 229 A \emph{LinuxApplication} resource represents anything that can be executed
 230 on a Linux host as a BASH command.
 231
 232 \begin{lstlisting}[language=Python]
 233
 234 %cpaste
 235 def add_node(ec, host, user, ssh_key):
 236     node = ec.register_resource("LinuxNode")
 237     ec.set(node, "hostname", host)
 238     ec.set(node, "username", user)
 239     ec.set(node, "identity", ssh_key)
 240     ec.set(node, "cleanHome", True)
 241     ec.set(node, "cleanProcesses", True)
 242     return node
 243
 244 def add_app(ec, command, node):
 245     app = ec.register_resource("LinuxApplication")
 246     ec.set(app, "command", command)
 247     ec.register_connection(app, node)
 248     return app
 249 --
 250
 251 \end{lstlisting}
 252
 253 The method \textit{register\_resource} declares a resource instance to the
 254 Experiment Controller. The method \textit{register\_connection} indicates
 255 that two resources will interact during the experiment.
 256 Note that invoking \textit{add\_node} or \textit{add\_app} has no effect other
 257 than informing the EC about the resources that will be used during the experiment.
 258 The actual deployment of the experiment requires the method \textit{deploy} to
 259 be invoked.
 260
 261 The Resource Managers (RM) that abstract the concrete resources expose
 262 some configuration attributes. In the LinuxNode RM we set the \emph{hostname}
 263 and \emph{username} as attributes, while in the LinuxApplication RM
 264 we set the \emph{command} attribute.
 265
 266 Apart from the \emph{command} attribute, the \emph{LinuxApplication}
 267 ResourceManager exposed several other attributes
 268 that permit to upload, compile and install arbitrary sources,
 269 to run any application might be needed to run an experiment.
 270 More details will be given in the following sections of this document.
 271
 272 Lets now use these functions to describe the experiment we will run.
 273 Choose a host where you have an account, and can access using SSH
 274 key authentication. Define string variables with the right
 275 values for the  \emph{hostname}, \emph{username} and the path to the
 276 SSH public key in \emph{ssh\_key}, and then type the following lines.
 277
 278 \begin{lstlisting}[language=Python]
 279
 280 node = add_node(ec, hostname, username, ssh_key)
 281 app = add_app(ec, "ping -c3 nepi.inria.fr",  node)
 282
 283 \end{lstlisting}
 284
 285 Now that we have described our simple PING experiment, we can deploy
 286 it. Invoking the \emph{deploy} command will not only configure the
 287 resource but also automatically launch the applications.
 288
 289 \begin{lstlisting}[language=Python]
 290
 291  ec.deploy()
 292
 293 \end{lstlisting}
 294
 295 After some seconds, we should see some log messages informing about
 296 the progress of the deployment.
 297 If you now open another terminal and connect to the host through SSH,
 298 you should find some directories created by NEPI.
 299 You should see a directory named \emph{nepi-exp}, and under that directory
 300 you will find another with the identifier you gave when you created the
 301 experiment controller (the <exp-id>).
 302 Under the experiment directory, you will find directories for each of the
 303 resources deployed (e.g. \emph{node-1}, \emph{app-2}).
 304 The resource directories are named with a short string that identifies the
 305 type of resource (e.g. 'node', 'app', etc), followed by a unique number that
 306 uniquely identifies a given resource within the experiment,
 307 the global unique identifier (guid).
 308
 309 From the ipython console, we can check the deployment status of each resource
 310 by querying the EC with the method \emph{state}.
 311 The argument \emph{hr} stand for `human readable`, and will return a string
 312 state instead of a state number.
 313
 314 \begin{lstlisting}[language=Python]
 315
 316 ec.state(app, hr=True)
 317
 318 \end{lstlisting}
 319
 320 Once the LinuxApplication is STARTED, we can retrieve the PING output using
 321 stored as a \emph{trace} file on the host. For this we use use \emph{trace}
 322 method, and specify the resource and the trace name (i.e. stdout).
 323
 324 \begin{lstlisting}[language=Python]
 325
 326  ec.trace(app, "stdout")
 327
 328 \end{lstlisting}
 329
 330 That is it. We can terminate the experiment by invoking the method \emph{shutdown}.
 331
 332 \begin{lstlisting}[language=Python]
 333
 334  ec.shutdown()
 335
 336 \end{lstlisting}
 337
 338
 339