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 version 2 as
   8 %    published by the Free Software Foundation;
   9 %
  10 %    This program is distributed in the hope that it will be useful,
  11 %    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 %    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 %    GNU General Public License for more details.
  14 %
  15 %    You should have received a copy of the GNU General Public License
  16 %    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 %
  18 % Author: Alina Quereilhac <alina.quereilhac@inria.fr>
  19 %
  20 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  21
  22 \section{What is NEPI?}
  23
  24 NEPI is not a network simulator, nor an emulator or a testbed.
  25 NEPI is a Python library that provides classes to describe and
  26 run network experiments on different experimentation platforms
  27 (e.g. Planetlab, OMF wireless testbeds, network simulators, etc).
  28
  29 Imagine that you want to run an experiment to test on the Internet
  30 a distributed application you just implemented.
  31 You can use NEPI to automate deployment of your application on
  32 the PlanetLab testbed, run the experiment, and then collect result files
  33 to your local machine.
  34 NEPI aims at providing a re-usable code base to run network
  35 experiments on target experimentation platforms, and in this
  36 way decrease the time you spend developing platform-specific
  37 scripts and debugging them.
  38
  39 NEPI is a network experiment management framework that provides a
  40 simple way of describing network experiments, and the logic to
  41 automatically deploy those experiments on the target experimentation
  42 environments.
  43 It also provides the means to control the resources used in the experiment
  44 (e.g. Nodes, applications, switches, virtual machines, routing table entries,
  45 etc) during experiment execution, and to collect results generated by
  46 the experiment to a local repository.
  47
  48 The experiment deployment and control are done by the
  49 ExperimentController (EC), which is the entity responsible for the
  50 global orchestration of the experiment.
  51 The EC knows nothing about how to manage specific resources
  52 (e.g. how to configure a network interface in a PlanetLab node),
  53 instead it delegates resource management to platform-specific
  54 entities called Resource Manager (RM).
  55 The RMs are responsible for controlling resources
  56 (e.g. Linux hosts, Open vSwitches on PlanetLab
  57 nodes, etc). Different types of resources are be controlled by
  58 specific RMs.
  59 All RMs implement a same API that the EC uses to communicate
  60 with them in a uniform way.
  61
  62 NEPI can not control all existing resources
  63 on all existing experimentation platforms by default.
  64 However, arbitrary resources can be controlled in NEPI if the
  65 corresponding Resource Manager is implemented for it.
  66 Fortunately, NEPI already provides several ResourceManagers to
  67 manage different resources on a variety of testbeds, and new
  68 Resource Manager classes can be extended from existing ones by
  69 the experimenters.
  70 The idea behind NEPI is to support running network experiments on
  71 potentially any experimentation platform, using a single
  72 software tool, instead of using a dedicated software for
  73 each platform.
  74
  75 \section{What does a NEPI script look like?}
  76 \label{faq:ping_example}
  77
  78 Here is a very simple experiment example, which runs a PING
  79 to "nepi.inria.fr" from a given host.
  80 Note that you will need to replace the hostname, username, and
  81 ssh\_key variables va to run the example.
  82
  83 \begin{lstlisting}[language=Python]
  84 from nepi.execution.ec import ExperimentController
  85
  86 ec = ExperimentController(exp_id="myexperiment")
  87
  88 hostname = # Host that can be accessed with an SSH account
  89 username = # SSH user account on host
  90 ssh_key = # Path to SSH public key file to access host
  91
  92 node = ec.register_resource("linux::Node")
  93 ec.set(node, "hostname", hostname)
  94 ec.set(node, "username", username)
  95 ec.set(node, "identity", ssh_key)
  96
  97 app = ec.register_resource("linux::Application")
  98 ec.set(app, "command", "ping -c3 nepi.inria.fr")
  99 ec.register_connection(app, node)
 100
 101 ec.deploy()
 102
 103 ec.wait_finished(app)
 104
 105 print ec.trace(app, "stdout")
 106
 107 ec.shutdown()
 108
 109 \end{lstlisting}
 110
 111 \section{What does NEPI stands for?}
 112
 113 It stands for Network Experiment Programming Interface.
 114
 115 \section{Who developed NEPI?}
 116
 117 NEPI was developed at INRIA, Sophia Antipolis France.
 118 A first prototype was implemented in 2010.
 119 Versions 1.0 and 2.0 were released in 2011 and 2012, respectively.
 120 The current NEPI version is 3.0.
 121
 122 The following people have contributed to the project:
 123
 124 \begin{itemize}
 125   \item NEPI version 3.0: Alina Quereilhac, Julien Tribino, Lucia Guevgeozian Odizzio, Alexandros Kouvakas
 126   \item NEPI versions 1.0 and 2.0: Alina Quereilhac, Claudio Freire, Martin Ferrari, Mathieu Lacage
 127   \item NEPI prototype: Martin Ferrari, Mathieu Lacage
 128   \item Other contributors: Dirk Hasselbalch
 129 \end{itemize}
 130
 131 \section{Is it free?}
 132
 133 Yes, NEPI is free software. It is free to use, free to modify, free to share.
 134 NEPI v2.0 is licensed under GPL v2, so you can do whatever you want with it,
 135 as long as you keep the same license.
 136
 137 \section{How can I contribute?}
 138
 139 There are many ways you can contribute to the project.
 140 The first one is using it and reporting bugs.
 141 You can report bugs on the NEPI bugzilla page at:
 142
 143 \url{http://nepi.inria.fr/bugzilla} \\
 144
 145 You can also become a part of the NEPI community and join our mailing lists:
 146
 147 \begin{itemize}
 148     \item To subscribe to the users mailing list at \textit{nepi-users@inria.fr}
 149         you can send an email to \textit{sympa@inria.fr} with subject
 150         \textit{Subscribe nepi-users <put-your-user-name-here>}
 151     \item To subscribe to the developers mailing list at \textit{nepi-developers@inria.fr}
 152         you can send an email to \textit{sympa@inria.fr} with subject
 153         \textit{Subscribe nepi-developers <put-your-user-name-here>}
 154     \end{itemize}
 155
 156 To contribute with bug fixes and new features, please send your code patch
 157 to the \textit{nepi-developers} list.
 158
 159 \section{How can I report a bug ?}
 160
 161 To report a bug take a look at the NEPI bugzilla page at :
 162
 163 \url{http://nepi.inria.fr/bugzilla} \\
 164
 165 \section{Where can I get more information?}
 166
 167 For more information visit NEPI web site at:
 168
 169 \url{http://nepi.inria.fr} \\
 170
 171