doc/user_manual/faq.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 \section{What is NEPI?}
  24
  25 NEPI is not a network simulator, nor an emulator or a testbed.
  26 NEPI is a Python library that provides classes to describe and
  27 run network experiments on different experimentation platforms
  28 (e.g. Planetlab, OMF wireless testbeds, network simulators, etc).
  29
  30 Imagine that you want to run an experiment to test a distributed
  31 application you just coded, on the Internet.
  32 You can use NEPI to deploy your application on PlanetLab
  33 nodes, run the experiment, and collect result files
  34 you might have generated during the
  35 experiment (e.g. pcap files from tcpudmps).
  36
  37 Sure, you could do this by coding your own BASH script, but
  38 it will probably take more time and painful hours of debugging
  39 if you want to do it right.
  40 NEPI aims at providing a re-usable code base to run network
  41 experiments on target experimentation platforms, so to
  42 decrease the time  you spend in developing platform specific
  43 scripts or programs, and debugging them.
  44
  45 In a nut-shell, NEPI is a network experiment
  46 management framework which provides a simple way of
  47 describing network experiments, and the logic to automatically
  48 deploy those experiments on the target experimentation environments.
  49 It also provides the means to control the resources used in the experiment
  50 (e.g. Nodes, applications, switches, virtual machines, routing table entries,
  51 etc ) during experiment execution, and to collect results generated by
  52 the experiment to a local repository.
  53
  54 The experiment deployment and control is done by the
  55 Experiment Controller (EC) entity, which is responsible for the
  56 global orchestration of the experiment.
  57 The EC knows nothing about how to manage specific resources
  58 (e.g. how to configure a network interface in a PlanetLab node),
  59 instead it delegates those tasks to entities called Resource Manager (RM).
  60
  61 The RMs are responsible of controlling single resources
  62 (e.g. a Linux host, an Open vSwitched on PlanetLab
  63 nodes, etc). Different types of resources will be controlled by
  64 different RMs, specifically adpated to control them.
  65 All RMs implement a same external interface, that the EC uses
  66 to control them in a uniform way.
  67
  68 NEPI is not magical, it can not control all existing resources
  69 on all existing experimentation platforms by default.
  70 However, potentially any resource could be controlled by
  71 NEPI if the adequate Resource Manager is implemented for it.
  72 Fortunately, NEPI already provides several Resource Managers for
  73 different resources on a variety of testbeds, and new
  74 Resource Manager classes can be extended from existing ones,
  75 to control new types of resources.
  76
  77 The idea behind NEPI is to enable runing network experiments on
  78 potentially any experimentation platform, using a single
  79 software tool, as opposite to using a dedicated software for
  80 each platform. An additional perk is that you don't have to deal
  81 with a lot of platform-specific gory details of setting up and
  82 configuring the resources (e.g. Creating a TAP device on Planetlab.
  83 If you ever had to do that, you know what I mean). Also,
  84 you could combine resources from different platforms in a same
  85 experiment, using just one script.
  86
  87 So, 'One ring to rule them all', sorry I meant, 'One tool to
  88 control them all'... or something like that.
  89 We though it was a good idea to abstract platform details
  90 behind a common resource management interface, and let
  91 NEPI deal with the details and give you back the results.
  92
  93 \section{What does a NEPI script look like ?}
  94 \label{faq:ping_example}
  95
  96 Here is a very simple experiment example, which runs a PING
  97 to "nepi.inria.fr" from a given host.
  98 Note that you will need to replace the hostname, username, and
  99 ssh\_key variables va to run the example.
 100
 101 \begin{lstlisting}[language=Python]
 102 from nepi.execution.ec import ExperimentController
 103
 104 ec = ExperimentController(exp_id = "myexperiment")
 105
 106 hostname = # Host that can be accessed with an SSH account
 107 username = # SSH user account on host
 108 ssh_key = # Path to SSH public key file to access host
 109
 110 node = ec.register_resource("linux::Node")
 111 ec.set(node, "hostname", hostname)
 112 ec.set(node, "username", username)
 113 ec.set(node, "identity", ssh_key)
 114
 115 app = ec.register_resource("linux::Application")
 116 ec.set(app, "command", "ping -c3 nepi.inria.fr")
 117 ec.register_connection(app, node)
 118
 119 ec.deploy()
 120
 121 ec.wait_finished(app)
 122
 123 print ec.trace(app, "stdout")
 124
 125 ec.shutdown()
 126
 127 \end{lstlisting}
 128
 129 \section{What does NEPI stands for?}
 130
 131 It stands for: Network Experiment Programming Interface.
 132
 133 \section{Who developed NEPI?}
 134
 135 NEPI was developed at INRIA, Sophia Antipolis France.
 136 A first prototype was implemented in 2010.
 137 Versions 1.0 and 2.0 were released in 2011 and 2012, respectively.
 138 The current version is 3.0, and it was completely redesigned and
 139 rewritten to broaden the scope, and to include several
 140 new features, which will be described in detail in this document.
 141 The following people has contributed to the project:
 142
 143 \begin{itemize}
 144   \item NEPI version 3.0: Alina Quereilhac, Julien Tribino, Lucia Guevgeozian Odizzio, Alexandros Kouvakas
 145   \item NEPI versions 1.0 and 2.0: Alina Quereilhac, Claudio Freire, Martin Ferrari, Mathieu Lacage
 146   \item NEPI prototype: Martin Ferrari, Mathieu Lacage
 147   \item Other contributors: Dirk Hasselbalch
 148 \end{itemize}
 149
 150 \section{Is it free?}
 151
 152 Yes, NEPI is free software. It is free to use, free to modify, free to share.
 153 NEPI v3.0 is licensed under GPL v3, so you can do whatever you want with it,
 154 as long as you keep the same license.
 155
 156 \section{How can I contribute?}
 157
 158 There are many ways you can contribute to the project.
 159 The first one is using it and reporting bugs.
 160 You can report bugs on the NEPI bugzilla page at:
 161
 162 \url{http://nepi.inria.fr/bugzilla} \\
 163
 164 You can also become a part of the NEPI community and join our mailing lists:
 165
 166 \begin{itemize}
 167     \item To subscribe to the users mailing list at \textit{nepi-users@inria.fr}
 168         you can send an email to \textit{sympa@inria.fr} with subject
 169         \textit{Subscribe nepi-users <put-your-user-name-here>}
 170     \item To subscribe to the developers mailing list at \textit{nepi-developers@inria.fr}
 171         you can send an email to \textit{sympa@inria.fr} with subject
 172         \textit{Subscribe nepi-developers <put-your-user-name-here>}
 173     \end{itemize}
 174
 175 To contribute with bug fixes and new features, please send your code patch
 176 to the \textit{nepi-developers} list.
 177
 178 \section{How can I report a bug ?}
 179
 180 To report a bug take a look at the NEPI bugzilla page at :
 181
 182 \url{http://nepi.inria.fr/bugzilla} \\
 183
 184 \section{Where can I get more information ?}
 185
 186 For more information visit NEPI web site at :
 187
 188 \url{http://nepi.inria.fr} \\
 189
 190