From: Alina Quereilhac Date: Mon, 30 Mar 2015 16:48:20 +0000 (+0200) Subject: user manual X-Git-Tag: nepi-3.2.4-pypi~3^2~2 X-Git-Url: http://git.onelab.eu/?p=nepi.git;a=commitdiff_plain;h=8b8d0779bade89727a816e8dd123bbacb6af9aee user manual --- diff --git a/doc/user_manual/abstract_topology_mapping.odg b/doc/user_manual/abstract_topology_mapping.odg index 1bf720ac..7b1d97a4 100644 Binary files a/doc/user_manual/abstract_topology_mapping.odg and b/doc/user_manual/abstract_topology_mapping.odg differ diff --git a/doc/user_manual/abstract_topology_mapping.pdf b/doc/user_manual/abstract_topology_mapping.pdf index 6a13252f..fe682a53 100644 Binary files a/doc/user_manual/abstract_topology_mapping.pdf and b/doc/user_manual/abstract_topology_mapping.pdf differ diff --git a/doc/user_manual/abstract_topology_mapping.png b/doc/user_manual/abstract_topology_mapping.png index 607216a4..7183a37c 100644 Binary files a/doc/user_manual/abstract_topology_mapping.png and b/doc/user_manual/abstract_topology_mapping.png differ diff --git a/doc/user_manual/abstract_topology_vs_executable_description.odg b/doc/user_manual/abstract_topology_vs_executable_description.odg index aeb644fa..5db24ec1 100644 Binary files a/doc/user_manual/abstract_topology_vs_executable_description.odg and b/doc/user_manual/abstract_topology_vs_executable_description.odg differ diff --git a/doc/user_manual/abstract_topology_vs_executable_description.png b/doc/user_manual/abstract_topology_vs_executable_description.png index 7e1dfa59..5d7884ca 100644 Binary files a/doc/user_manual/abstract_topology_vs_executable_description.png and b/doc/user_manual/abstract_topology_vs_executable_description.png differ diff --git a/doc/user_manual/debugging.tex b/doc/user_manual/debugging.tex index 9185dcdd..bc06fd95 100644 --- a/doc/user_manual/debugging.tex +++ b/doc/user_manual/debugging.tex @@ -19,4 +19,12 @@ % %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -TODO +NEPI can be run in debug mode by using the environment variable NEPI\_LOGLEVEL +to \textit{debug}. By default the NEPI runs in \textit{info} mode. + +\begin{verbatim} +$ export NEPI_LOGLEVEL=info #Info mode +$ export NEPI_LOGLEVEL=debug # Debug mode +\end{verbatim} + + diff --git a/doc/user_manual/ec_api.tex b/doc/user_manual/ec_api.tex index 40b73ef7..1b05fb7f 100644 --- a/doc/user_manual/ec_api.tex +++ b/doc/user_manual/ec_api.tex @@ -54,7 +54,7 @@ generate a unique id for the experiment. \begin{lstlisting}[language=Python] -ec = ExperimentController(exp_id = "my-exp-id") +ec = ExperimentController(exp_id="my-exp-id") \end{lstlisting} @@ -469,7 +469,7 @@ object? -> Details about 'object', use 'object??' for extra details. In [1]: from nepi.execution.ec import ExperimentController -In [2]: ec = ExperimentController(exp_id = "test-tap") +In [2]: ec = ExperimentController(exp_id="test") In [3]: help(ec.set) diff --git a/doc/user_manual/faq.tex b/doc/user_manual/faq.tex index d4e4efc3..68da1129 100644 --- a/doc/user_manual/faq.tex +++ b/doc/user_manual/faq.tex @@ -26,70 +26,53 @@ NEPI is a Python library that provides classes to describe and run network experiments on different experimentation platforms (e.g. Planetlab, OMF wireless testbeds, network simulators, etc). -Imagine that you want to run an experiment to test a distributed -application you just coded, on the Internet. -You can use NEPI to deploy your application on PlanetLab -nodes, run the experiment, and collect result files -you might have generated during the -experiment (e.g. pcap files from tcpudmps). - -Sure, you could do this by coding your own BASH script, but -it will probably take more time and painful hours of debugging -if you want to do it right. +Imagine that you want to run an experiment to test on the Internet +a distributed application you just implemented. +You can use NEPI to automate deployment of your application on +the PlanetLab testbed, run the experiment, and then collect result files +to your local machine. NEPI aims at providing a re-usable code base to run network -experiments on target experimentation platforms, so to -decrease the time you spend in developing platform specific -scripts or programs, and debugging them. - -In a nut-shell, NEPI is a network experiment -management framework which provides a simple way of -describing network experiments, and the logic to automatically -deploy those experiments on the target experimentation environments. +experiments on target experimentation platforms, and in this +way decrease the time you spend developing platform-specific +scripts and debugging them. + +NEPI is a network experiment management framework that provides a +simple way of describing network experiments, and the logic to +automatically deploy those experiments on the target experimentation +environments. It also provides the means to control the resources used in the experiment (e.g. Nodes, applications, switches, virtual machines, routing table entries, -etc ) during experiment execution, and to collect results generated by +etc) during experiment execution, and to collect results generated by the experiment to a local repository. -The experiment deployment and control is done by the -Experiment Controller (EC) entity, which is responsible for the +The experiment deployment and control are done by the +ExperimentController (EC), which is the entity responsible for the global orchestration of the experiment. The EC knows nothing about how to manage specific resources (e.g. how to configure a network interface in a PlanetLab node), -instead it delegates those tasks to entities called Resource Manager (RM). - -The RMs are responsible of controlling single resources -(e.g. a Linux host, an Open vSwitched on PlanetLab -nodes, etc). Different types of resources will be controlled by -different RMs, specifically adpated to control them. -All RMs implement a same external interface, that the EC uses -to control them in a uniform way. - -NEPI is not magical, it can not control all existing resources +instead it delegates resource management to platform-specific +entities called Resource Manager (RM). +The RMs are responsible for controlling resources +(e.g. Linux hosts, Open vSwitches on PlanetLab +nodes, etc). Different types of resources are be controlled by +specific RMs. +All RMs implement a same API that the EC uses to communicate +with them in a uniform way. + +NEPI can not control all existing resources on all existing experimentation platforms by default. -However, potentially any resource could be controlled by -NEPI if the adequate Resource Manager is implemented for it. -Fortunately, NEPI already provides several Resource Managers for -different resources on a variety of testbeds, and new -Resource Manager classes can be extended from existing ones, -to control new types of resources. - -The idea behind NEPI is to enable runing network experiments on +However, arbitrary resources can be controlled in NEPI if the +corresponding Resource Manager is implemented for it. +Fortunately, NEPI already provides several ResourceManagers to +manage different resources on a variety of testbeds, and new +Resource Manager classes can be extended from existing ones by +the experimenters. +The idea behind NEPI is to support running network experiments on potentially any experimentation platform, using a single -software tool, as opposite to using a dedicated software for -each platform. An additional perk is that you don't have to deal -with a lot of platform-specific gory details of setting up and -configuring the resources (e.g. Creating a TAP device on Planetlab. -If you ever had to do that, you know what I mean). Also, -you could combine resources from different platforms in a same -experiment, using just one script. - -So, 'One ring to rule them all', sorry I meant, 'One tool to -control them all'... or something like that. -We though it was a good idea to abstract platform details -behind a common resource management interface, and let -NEPI deal with the details and give you back the results. - -\section{What does a NEPI script look like ?} +software tool, instead of using a dedicated software for +each platform. + +\section{What does a NEPI script look like?} \label{faq:ping_example} Here is a very simple experiment example, which runs a PING @@ -100,7 +83,7 @@ ssh\_key variables va to run the example. \begin{lstlisting}[language=Python] from nepi.execution.ec import ExperimentController -ec = ExperimentController(exp_id = "myexperiment") +ec = ExperimentController(exp_id="myexperiment") hostname = # Host that can be accessed with an SSH account username = # SSH user account on host @@ -127,17 +110,16 @@ ec.shutdown() \section{What does NEPI stands for?} -It stands for: Network Experiment Programming Interface. +It stands for Network Experiment Programming Interface. \section{Who developed NEPI?} NEPI was developed at INRIA, Sophia Antipolis France. A first prototype was implemented in 2010. Versions 1.0 and 2.0 were released in 2011 and 2012, respectively. -The current version is 3.0, and it was completely redesigned and -rewritten to broaden the scope, and to include several -new features, which will be described in detail in this document. -The following people has contributed to the project: +The current NEPI version is 3.0. + +The following people have contributed to the project: \begin{itemize} \item NEPI version 3.0: Alina Quereilhac, Julien Tribino, Lucia Guevgeozian Odizzio, Alexandros Kouvakas @@ -149,7 +131,7 @@ The following people has contributed to the project: \section{Is it free?} Yes, NEPI is free software. It is free to use, free to modify, free to share. -NEPI v3.0 is licensed under GPL v3, so you can do whatever you want with it, +NEPI v2.0 is licensed under GPL v2, so you can do whatever you want with it, as long as you keep the same license. \section{How can I contribute?} @@ -180,9 +162,9 @@ To report a bug take a look at the NEPI bugzilla page at : \url{http://nepi.inria.fr/bugzilla} \\ -\section{Where can I get more information ?} +\section{Where can I get more information?} -For more information visit NEPI web site at : +For more information visit NEPI web site at: \url{http://nepi.inria.fr} \\ diff --git a/doc/user_manual/getting_started.tex b/doc/user_manual/getting_started.tex index a9bb5ead..c9e667f4 100644 --- a/doc/user_manual/getting_started.tex +++ b/doc/user_manual/getting_started.tex @@ -86,7 +86,7 @@ then you can install Python and the rest of the dependencies as follows: \endgroup -To use Python you will need to set the PATH environmental variable as: +To use Python you will need to set the PATH environmen variable as: \begingroup \fontsize{10pt}{12pt}\selectfont @@ -125,7 +125,7 @@ control system. The Mercurial NEPI repo can also be browsed online at: \\ \fontsize{10pt}{12pt}\selectfont \begin{verbatim} -$ hg clone http://nepi.inria.fr/code/nepi -r nepi-3-dev +$ hg clone http://nepi.inria.fr/code/nepi -r nepi-3.2.0 \end{verbatim} \endgroup @@ -289,8 +289,8 @@ ec = ExperimentController(exp_id = "") \end{lstlisting} Next we will define two Python functions: \emph{add\_node} and \emph{add\_app}. -The first one to register \textit{LinuxNodes} resources and the second one to -register LinuxApplications resources. +The first one to register linux::Node resources and the second one to +register linux::Application resources. \begin{lstlisting}[language=Python] @@ -300,7 +300,7 @@ def add_node(ec, hostname, username, ssh_key): ec.set(node, "hostname", hostname) ec.set(node, "username", username) ec.set(node, "identity", ssh_key) - ec.set(node, "cleanHome", True) + ec.set(node, "cleanExperiment", True) ec.set(node, "cleanProcesses", True) return node @@ -321,7 +321,7 @@ than informing the EC about the resources that will be used during the experimen The actual deployment of the experiment requires the method \textit{deploy} to be invoked. -The \textit{LinuxNode} resource exposes the hostname, username and identity +The linux::Node resource exposes the hostname, username and identity attributes. This attributes provide information about the SSH credentials needed to log in to the Linux host. The \textit{hostname} is the one that identifies the physical host you want @@ -330,13 +330,13 @@ valid account on that host, and the \textit{identity} attribute is the 'absolute' path to the SSH private key in your local computer that allows you to log in to the host. -The \textit{command} attribute of the \textit{LinuxApplication} resource +The \textit{command} attribute of the linux::Application resource expects a BASH command line string to be executed in the remote host. -Apart from the \emph{command} attribute, the \emph{LinuxApplication} +Apart from the \emph{command} attribute, the linux::Application resource exposes several other attributes that allow to upload, compile and install arbitrary sources. -The add\_app function registers a connection between a \textit{LinuxNode} and a -\textit{LinuxApplication}. +The add\_app function registers a connection between a linux::Node and a +linux::Application. Lets now use these functions to describe a simple experiment. Choose a host where you have an account, and can access using SSH @@ -344,9 +344,9 @@ key authentication. \begin{lstlisting}[language=Python] -hostname = "" -username = "" -identity = "" +hostname = +username = +identity = node = add_node(ec, hostname, username, ssh_key) app = add_app(ec, "ping -c3 nepi.inria.fr", node) @@ -395,7 +395,7 @@ the assigned to your EC, and inside that directory you should find one directory named node-1 which will contain the files (e.g. result traces) associated to the LinuxNode reosurce you just deployed. In fact for every resource deployed associated to that host (e.g. each -LinuxApplication), NEPI will create a directory to place files related to it. +linux::Application), NEPI will create a directory to place files related to it. The name of the directory identifies the type of resources (e.g. 'node', 'app', etc) and it is followed by the global unique identifier (guid). @@ -407,7 +407,7 @@ ec.state(app, hr=True) \end{lstlisting} -Once a \textit{LinuxApplication} has reached the state 'STARTED', +Once a linux::Application has reached the state 'STARTED', we can retrieve the 'stdout' trace, which should contain the output of the PING command. diff --git a/doc/user_manual/intro_dependencies_graph.pdf b/doc/user_manual/intro_dependencies_graph.pdf index 38833dd7..7837da6b 100644 Binary files a/doc/user_manual/intro_dependencies_graph.pdf and b/doc/user_manual/intro_dependencies_graph.pdf differ diff --git a/doc/user_manual/intro_resource.odg b/doc/user_manual/intro_resource.odg index b5c6207d..d4f8e489 100644 Binary files a/doc/user_manual/intro_resource.odg and b/doc/user_manual/intro_resource.odg differ diff --git a/doc/user_manual/intro_resource.pdf b/doc/user_manual/intro_resource.pdf index 6d8b74fe..46811d70 100644 Binary files a/doc/user_manual/intro_resource.pdf and b/doc/user_manual/intro_resource.pdf differ diff --git a/doc/user_manual/introduction.tex b/doc/user_manual/introduction.tex index a4c812ed..db886cc8 100644 --- a/doc/user_manual/introduction.tex +++ b/doc/user_manual/introduction.tex @@ -20,7 +20,7 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % Motivation -During the past decades, a wide variety of platforms to conduct network +During the past decades a wide variety of platforms to conduct network experiments, including simulators, emulators and live testbeds, have been made available to the research community. Some of these platforms are tailored for very specific use cases (e.g. diff --git a/doc/user_manual/user_manual.pdf b/doc/user_manual/user_manual.pdf index 2019a517..a095dab2 100644 Binary files a/doc/user_manual/user_manual.pdf and b/doc/user_manual/user_manual.pdf differ diff --git a/doc/user_manual/user_manual.tex b/doc/user_manual/user_manual.tex index 9c6d943b..39c74a10 100644 --- a/doc/user_manual/user_manual.tex +++ b/doc/user_manual/user_manual.tex @@ -161,9 +161,9 @@ \label{ec_api} \input{ec_api.tex} -\chapter{Supported resources} -\label{supported_resources} -\input{supported_resources.tex} +%\chapter{Supported resources} +%\label{supported_resources} +%\input{supported_resources.tex} %%\chapter{ExperimentController internals} %%\label{ec_internals} @@ -185,9 +185,9 @@ %%\label{unit_testing} %%\input{unit_testing.tex} -\chapter{Release Cycle} -\label{release_cycle} -\input{release_cycle.tex} +%\chapter{Release Cycle} +%\label{release_cycle} +%\input{release_cycle.tex} %%\chapter{Coding Style} %%\label{coding_style}