From: Alina Quereilhac Date: Thu, 14 Nov 2013 17:04:24 +0000 (+0100) Subject: Adding user manual sources X-Git-Tag: nepi-3.0.0~14 X-Git-Url: http://git.onelab.eu/?a=commitdiff_plain;h=16b00f15bf8a2364cd7a3bb7b62035064059df16;hp=75cf4cdc87224cca0a40914d15b0913d2250ad62;p=nepi.git Adding user manual sources --- diff --git a/doc/user_manual/coding_style.tex b/doc/user_manual/coding_style.tex new file mode 100644 index 00000000..96a17414 --- /dev/null +++ b/doc/user_manual/coding_style.tex @@ -0,0 +1,23 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +TODO diff --git a/doc/user_manual/debugging.tex b/doc/user_manual/debugging.tex new file mode 100644 index 00000000..96a17414 --- /dev/null +++ b/doc/user_manual/debugging.tex @@ -0,0 +1,23 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +TODO diff --git a/doc/user_manual/ec_api.tex b/doc/user_manual/ec_api.tex new file mode 100644 index 00000000..68599dd3 --- /dev/null +++ b/doc/user_manual/ec_api.tex @@ -0,0 +1,42 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +\begin{itemize} + \item EC API + \begin{itemize} + \item register resource + \item RM States (State transition DIAGRAM) + \item RM Actions + \item Attributes + \item The critical attribute + \item Traces (how to collect traces to the local repo, talk about the Collector RM) + \item deploy (interactive deployment) + \item workflow - register condition + \end{itemize} + \item Resource Factory + \begin{itemize} + \item Populate factory (happens automatically) + \item How to discover available rm types and their resources + \end{itemize} +\end{itemize} + diff --git a/doc/user_manual/ec_internals.tex b/doc/user_manual/ec_internals.tex new file mode 100644 index 00000000..ecca184f --- /dev/null +++ b/doc/user_manual/ec_internals.tex @@ -0,0 +1,32 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% ExperimentController internals + +\begin{itemize} + \item the RMs dictionary + \item The scheduler queue, the tasks dictionary, the schedule method + \item the processing thread and the \_process method, the inmediate execution queueu and the ParallelRunner + \item the \_execute method + \item The deploy method, deployment groups + \item The FailManager and what happens upon release (critical attribute) +\end{itemize} diff --git a/doc/user_manual/extending_nepi.tex b/doc/user_manual/extending_nepi.tex new file mode 100644 index 00000000..de11e441 --- /dev/null +++ b/doc/user_manual/extending_nepi.tex @@ -0,0 +1,24 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +TODO + diff --git a/doc/user_manual/faq.tex b/doc/user_manual/faq.tex new file mode 100644 index 00000000..4b227171 --- /dev/null +++ b/doc/user_manual/faq.tex @@ -0,0 +1,191 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{What is NEPI?} + +NEPI is not a network simulator, nor an emulator or a testbed. +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. +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. +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 +the experiment to a local repository. + +The experiment deployment and control is done by the +Experiment Controller (EC) entity, which is 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 +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 +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 ide 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 ?} +\label{faq:ping_example} + +Here is a very simple experiment example, which runs a PING +to "nepi.inria.fr" from a given host. +Note that you will need to replace the hostname, username, and +ssh\_key variables va to run the example. + +\begin{lstlisting}[language=Python] +from nepi.execution.ec import ExperimentController + +ec = ExperimentController(exp_id = "myexperiment") + +hostname = # Host that can be accessed with an SSH account +username = # SSH user account on host +ssh_key = # Path to SSH public key file to access host + +node = ec.register_resource("LinuxNode") +ec.set(node, "hostname", host) +ec.set(node, "username", user) +ec.set(node, "identity", ssh_key) + +app = ec.register_resource("LinuxApplication") +ec.set(app, "command", "ping -c3 nepi.inria.fr") +ec.register_connection(app, node) + +ec.deploy() + +ec.wait_finished(app) + +print ec.trace(app, "stdout") + +ec.shutdown() + +\end{lstlisting} + +\section{What does NEPI stands for?} + +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 cool +new features, which will be described in detail in this document. +The following people has contributed to the project: + +\begin{itemize} + \item NEPI version 3.0: Alina Quereilhac, Julien Tribino, Lucia Guevgeozian Odizzio, Alexandros Kouvakas + \item NEPI versions 1.0 and 2.0: Alina Quereilhac, Claudio Freire, Martin Ferrari, Mathieu Lacage + \item NEPI prototype: Martin Ferrari, Mathieu Lacage + \item Other contributors: Dirk Hasselbalch +\end{itemize} + +\section{Is it free?} + +Yes, NEPI is free software. It is free to use, free to to modify, free to share. +NEPI v3.0 is licensed under GPL v3, so you can do whatever you want with it, +as long as you keep the same license. + +\section{How can I contribute?} + +There are many ways you can contribute to the project. +The first one is using it and reporting bugs. +You can report bugs on the NEPI bugzilla page +(\textbf{not yet set-up, so for now send the bugs by email to the users list}): \\ + +\url{https://nepi.inria.fr/bugzilla/} \\ + +You can also become a part of the NEPI community and join our mailing lists: + +\begin{itemize} + \item To subscribe to the users mailing list at \textit{nepi-users@inria.fr} + you can send an email to \textit{sympa@inria.fr} with subject + \textit{Subscribe nepi-users } + \item To subscribe to the developers mailing list at \textit{nepi-developers@inria.fr} + you can send an email to \textit{sympa@inria.fr} with subject + \textit{Subscribe nepi-developers } + \end{itemize} + +To contribute with bug fixes and new features, please send your code patch +to the \textit{nepi-developers} list. + +\section{How can I report a bug ?} + +To report a bug take a look at the NEPI bugzilla page at: + +\url{https://nepi.inria.fr/bugzilla/} \\ + +\section{Where can I get more information ?} + +For more information visit NEPI web site at + +\url{https://nepi.inria.fr} \\ + + diff --git a/doc/user_manual/getting_started.tex b/doc/user_manual/getting_started.tex new file mode 100644 index 00000000..29802200 --- /dev/null +++ b/doc/user_manual/getting_started.tex @@ -0,0 +1,339 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +NEPI is written in Python, so you will need to install Python before +before being able to run experiments with NEPI. +NEPI is known to work on Linux (Fedore, Debian, Ubuntu) and Mac (OS X). + +\section{Dependencies} + +Dependencies for NEPI vary according to the features you want to enable. +Make sure the following dependencies are correctly installed in your system +before using NEPI. \\ + +Mandatory dependencies: +\begin{itemize} + \item Python 2.6+ + \item Mercurial +\end{itemize} + +Optional dependencies: +\begin{itemize} + \item SleekXMPP - Required to run experiments on OMF testbeds +\end{itemize} + +\subsection{Install dependencies on Debian/Ubuntu} + +\begingroup + \fontsize{10pt}{12pt}\selectfont + +\begin{verbatim} + $ sudo aptitude install -y python mercurial +\end{verbatim} + +\endgroup + +\subsection{Install dependencies on Fedora} + +\begingroup + \fontsize{10pt}{12pt}\selectfont + +\begin{verbatim} + $ sudo yum install -y python mercurial +\end{verbatim} + +\endgroup + +\subsection{Install dependencies on Mac} + +First install homebrew (\url{http://mxcl.github.io/homebrew/}), +then install Python. + +\begingroup + \fontsize{10pt}{12pt}\selectfont + +\begin{verbatim} + $ brew install python +\end{verbatim} + +\endgroup + +\subsection{Install SleekXMPP} + +You will need \textit{git} to get the SleekXMPP sources. + +\begingroup + \fontsize{10pt}{12pt}\selectfont + +\begin{verbatim} + $ git clone -b develop git://github.com/fritzy/SleekXMPP.git + $ cd SleekXMPP + $ sudo python setup.py install +\end{verbatim} + +\endgroup + +\section{The source code} + +To get NEPI's source code you will need Mercurial version +control system. The Mercurial NEPI repo can also be browsed online at: \\ + +\url{http://nepi.inria.fr/code/nepi/} + +\subsection{Clone the repo} + +\begingroup + \fontsize{10pt}{12pt}\selectfont + +\begin{verbatim} +$ hg clone http://nepi.inria.fr/code/nepi -r nepi-3.0-release +\end{verbatim} + +\endgroup + +\section{Install NEPI in your system} + +You don't need to install NEPI in your system to be able to run +experiments. However this might be convenient if you don't +plan to modify or extend the sources. + +To install NEPI, just run \emph{make install} in the NEPI source +folder. + +\begingroup + \fontsize{10pt}{12pt}\selectfont + +\begin{verbatim} + $ cd nepi + $ make install +\end{verbatim} + +\endgroup + +If you are developing your own NEPI extensions, the installed +NEPI version might interfere with your work. +In this case it is probably more convenient to tell +Python where to find the NEPI sources, using the PYTHONPATH +environmental variable, when you run a NEPI script. + +\begingroup + \fontsize{10pt}{12pt}\selectfont + +\begin{verbatim} + $ PYTHONATH=$PYTHONPATH:/src python experiment.py +\end{verbatim} + +\endgroup + +\section{Run experiments} + +There are two ways you can use NEPI to run your experiments. +The first one is writing a Python script, which will import +NEPI libraries, and run it. +The second one is in interactive mode by using Python console. + +\subsection{Run from script} + +Writing a simple NEPI expeiment script is easy. +Take a look at the example in the FAQ section \ref{faq:ping_example}. +Once you have written down the script, you can run it using +Python. Note that since NEPI is not yet installed in your system, +you will need to export the path to NEPI's source code to +the PYTHONPATH environment variable, so that Python can find +NEPI's libraries. + +\begingroup + \fontsize{10pt}{12pt}\selectfont + +\begin{verbatim} + $ export PYTHONPATH=/src:$PYTHONPATH + $ python first-experiment.py +\end{verbatim} + +\endgroup + +\subsection{Run interactively} + +The Python interpreter can be used as an interactive console to execute +Python instructions. +We can take advantage of this feature, to interactively run experiments +with NEPI. We use the \textit{ipython} console for the example below, +you can install it with \textit{sudo yum/aptitude install ipython} on +Fedora/Debian. + +\begingroup + \fontsize{10pt}{12pt}\selectfont + +\begin{verbatim} +$ export PYTHONPATH=/src:$PYTHONPATH +$ ipython +Python 2.7.3 (default, Jan 2 2013, 13:56:14) +Type "copyright", "credits" or "license" for more information. + +IPython 0.13.1 -- An enhanced Interactive Python. +? -> Introduction and overview of IPython's features. +%quickref -> Quick reference. +help -> Python's own help system. +object? -> Details about 'object', use 'object??' for extra details. + +\end{verbatim} + +\endgroup + +With ipython, if you want to paste many lines at once you will need to type +\emph{\%cpaste} and finish the paste block with \emph{\-\-}. + +The first thing we have to do is to import the NEPI classes +we will use. +In particular we need to import the ExperimentController class. + +\begin{lstlisting}[language=Python] + +from nepi.execution.ec import ExperimentController + +\end{lstlisting} + +Then we need to create an ExperimentController instance. +The \textit{exp-id} argument serves as a human readable identifier +for the experiment to be ran. + +\begin{lstlisting}[language=Python] + +ec = ExperimentController(exp_id = "") + +\end{lstlisting} + +Next we will define two Python functions, one to register \emph{LinuxNode} +resources and the other to register \emph{LinuxApplication} resources. +A \emph{LinuxNode} resource (or ResourceManager) will serve as an abstraction +to a Linux host resource, that can be accessed using SSH key authentication. +A \emph{LinuxApplication} resource represents anything that can be executed +on a Linux host as a BASH command. + +\begin{lstlisting}[language=Python] + +%cpaste +def add_node(ec, host, user, ssh_key): + node = ec.register_resource("LinuxNode") + ec.set(node, "hostname", host) + ec.set(node, "username", user) + ec.set(node, "identity", ssh_key) + ec.set(node, "cleanHome", True) + ec.set(node, "cleanProcesses", True) + return node + +def add_app(ec, command, node): + app = ec.register_resource("LinuxApplication") + ec.set(app, "command", command) + ec.register_connection(app, node) + return app +-- + +\end{lstlisting} + +The method \textit{register\_resource} declares a resource instance to the +Experiment Controller. The method \textit{register\_connection} indicates +that two resource will interact during the experiment. +Note that invoking \textit{add\_node} or \textit{add\_app} has no effect other +than informing the EC about the resources that will be used during the experiment. +The actual deployment of the experiment requires the method \textit{deploy} to +be invoked. + +The Resource Managers (RM) that abstract the concrete resources expose +configuration attributes. In the LinuxNode RM we set the \emph{hostname} +and \emph{username} as attributes, while in the LinuxApplication RM +we set the \emph{command} attribute. + +Apart from teh \emph{command} attribute, the \emph{LinuxApplication} +ResourceManager exposed several other attributes +that permit to upload, compile and install arbitrary sources, +to run any application might be needed to run an experiment. +More details will be given in the following sections of this document. + +Lets now use these functions to describe the experiment we will run. +Choose a host where you have an account, and can access using SSH +key authentication. Define string variables with the right +values for the \emph{hostname}, \emph{username} and path to the +SSH public key in as \emph{ssh\_key}, and then type the following lines. + +\begin{lstlisting}[language=Python] + +node = add_node(ec, hostname, username, ssh_key) +app = add_app(ec, "ping -c3 nepi.inria.fr", node) + +\end{lstlisting} + +Now that we have described our simple PING experiment, we can deploy +it. Invoking the \emph{deploy} command will not only configure the +resource but also automatically launch the applications. + +\begin{lstlisting}[language=Python] + + ec.deploy() + +\end{lstlisting} + +After some seconds, we should see some log messages informing about +the progress of the deployment. +If you now open another terminal and connect to the host through SSH, +you should find some directories created by NEPI. +You should see a directory named \emph{nepi-exp}, and under that directory +you will find another with the identifier you gave when you created the +experiment controller (the ). +Under the experiment directory, you will find directories for each of the +resources deployed (e.g. \emph{node-1}, \emph{app-2}). +The resource directories are named with a short string that identifies the +type of resource (e.g. 'node', 'app', etc), followed by a unique number that +uniquely identifies a given resource within the experiment, +the global unique identifier (guid). + +From the ipython console, we can check the deployment status of each resource +by querying the EC with the method \emph{state}. +The argument \emph{hr} stand for `human readable`, and will return a string +state instead of a state number. + +\begin{lstlisting}[language=Python] + +ec.state(app, hr=True) + +\end{lstlisting} + +Once the LinuxApplication is STARTED, we can retrieve the PING output using +stored as a \emph{trace} file on the host. For this we use use \emph{trace} +method, and specify the resource and the trace name (i.e. stdout). + +\begin{lstlisting}[language=Python] + + ec.trace(app, "stdout") + +\end{lstlisting} + +That is it. We can terminate the experiment by invoking the method \emph{shutdown}. + +\begin{lstlisting}[language=Python] + + ec.shutdown() + +\end{lstlisting} + + + diff --git a/doc/user_manual/intro_dependencies_graph.odg b/doc/user_manual/intro_dependencies_graph.odg new file mode 100644 index 00000000..1c90f7f1 Binary files /dev/null and b/doc/user_manual/intro_dependencies_graph.odg differ diff --git a/doc/user_manual/intro_dependencies_graph.pdf b/doc/user_manual/intro_dependencies_graph.pdf new file mode 100644 index 00000000..38833dd7 Binary files /dev/null and b/doc/user_manual/intro_dependencies_graph.pdf differ diff --git a/doc/user_manual/intro_ec.odg b/doc/user_manual/intro_ec.odg new file mode 100644 index 00000000..9a99081c Binary files /dev/null and b/doc/user_manual/intro_ec.odg differ diff --git a/doc/user_manual/intro_ec.pdf b/doc/user_manual/intro_ec.pdf new file mode 100644 index 00000000..2078fdbb Binary files /dev/null and b/doc/user_manual/intro_ec.pdf differ diff --git a/doc/user_manual/intro_life_cycle.odg b/doc/user_manual/intro_life_cycle.odg new file mode 100644 index 00000000..7bc2e6bb Binary files /dev/null and b/doc/user_manual/intro_life_cycle.odg differ diff --git a/doc/user_manual/intro_life_cycle.pdf b/doc/user_manual/intro_life_cycle.pdf new file mode 100644 index 00000000..a5080940 Binary files /dev/null and b/doc/user_manual/intro_life_cycle.pdf differ diff --git a/doc/user_manual/intro_resource.odg b/doc/user_manual/intro_resource.odg new file mode 100644 index 00000000..34d93c57 Binary files /dev/null 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 new file mode 100644 index 00000000..0b0bba6a Binary files /dev/null and b/doc/user_manual/intro_resource.pdf differ diff --git a/doc/user_manual/intro_resource_management.odg b/doc/user_manual/intro_resource_management.odg new file mode 100644 index 00000000..43213068 Binary files /dev/null and b/doc/user_manual/intro_resource_management.odg differ diff --git a/doc/user_manual/intro_resource_management.pdf b/doc/user_manual/intro_resource_management.pdf new file mode 100644 index 00000000..c6347d60 Binary files /dev/null and b/doc/user_manual/intro_resource_management.pdf differ diff --git a/doc/user_manual/intro_state_transitions.odg b/doc/user_manual/intro_state_transitions.odg new file mode 100644 index 00000000..524f0173 Binary files /dev/null and b/doc/user_manual/intro_state_transitions.odg differ diff --git a/doc/user_manual/intro_state_transitions.pdf b/doc/user_manual/intro_state_transitions.pdf new file mode 100644 index 00000000..fa2fe50d Binary files /dev/null and b/doc/user_manual/intro_state_transitions.pdf differ diff --git a/doc/user_manual/intro_topo_graph.odg b/doc/user_manual/intro_topo_graph.odg new file mode 100644 index 00000000..747f1029 Binary files /dev/null and b/doc/user_manual/intro_topo_graph.odg differ diff --git a/doc/user_manual/intro_topo_graph.pdf b/doc/user_manual/intro_topo_graph.pdf new file mode 100644 index 00000000..c1bea355 Binary files /dev/null and b/doc/user_manual/intro_topo_graph.pdf differ diff --git a/doc/user_manual/introduction.tex b/doc/user_manual/introduction.tex new file mode 100644 index 00000000..1ef90d3c --- /dev/null +++ b/doc/user_manual/introduction.tex @@ -0,0 +1,275 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +% Motivation +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. +PlanetLab for very realistic Internet application level scenarios), +while others support more generic ones (e.g. ns-3 for controllable +and repeatable experimentation). Nevertheless, no single platform is +able to satisfy all possible scenarios, and so researchers often rely +on different platforms to evaluate their ideas. + +Given the huge diversity of available platforms, it is to be expected a +big disparity in the way to carry out an experiment between one platform and +another. Indeed, different platforms provide their own mechanisms to +access resources and different tools to conduct experiments. +These tools vary widely, for instance, to run a ns-3 simulation it is +necessary to write a C++ program, while to conduct and experiment using +PlanetLab nodes, one must first provision resources through a special web +service, and then connect to the nodes using SSH to launch any applications +involved in the experiment. + +Mastering such diversity of tools can be a daunting task, +but the complexity of conducting network experiments is not only limited +to having to master different tools and services. +Designing and implementing the programs and scripts to run an experiment +can be a time consuming and difficult task, specially if distributed +resources need to be synchronised to perform the right action at the +right time. Detecting and handling possible errors during experiment +execution also posses a challenge, even more so when dealing with large size +experiments. Additionally, difficulties related to instrumenting the +experiment and gathering the results must also be considered. + +% Challenge +In this context, the challenges that NEPI addresses are manifold. +Firstly, simplifying the complexity of running network experiments. +Secondly, simplifying the use of different experimentation platforms, +allowing to easily switch from one to another. +Thirdly, simplifying the +use of resources from different platforms at the same time in +a single experiment. + +% How? +The approach proposed by NEPI consists on exposing a generic API +that researchers can use to \emph{program} experiments, and +providing the libraries that can execute those experiments on +target network experimentation platforms. The API abstracts the +researchers from the details required to actually run an experiment +on a given platform, while the libraries provide the code to +automatically perform the steps necessary to deploy the experiment +and manage resources. + +The API is generic enough to allow describing potentially any +type of experiment, while the architecture of the libraries was +designed to be extensible to support arbitrary platforms. +A consequence of this is that any new platform can be supported in +NEPI without changing the API, in a way that is transparent +to the users. + +% +\section{Experiment Description} + +NEPI represents experiments as graphs of interconnected resources. +A resource is an abstraction of any component that takes part of an +experiment and that can be controlled by NEPI. +It can be a software or hardware component, it could be a virtual +machine, a switch, a remote application process, a sensor node, etc. + +Resources in NEPI are described by a set of attributes, traces and +connections. The attributes define the configuration of the resource, +the traces represent the results that can be collected for that resource +during the experiment and the connections represent how a resource relates +to other resources in th experiment. + +\begin{figure}[h] + \centering + \includegraphics[width=0.5\textwidth]{intro_resource} + \caption{Properties of a resource of type LinuxApplication} + \label{fig:intro_resources} +\end{figure} + +Examples of attributes are a linux host host name, an IP address to be +assigned to a network interface, a command to run as a remote application. +Examples of traces are the standard output or standard error of a +running application, a tcpdump on a network interface, etc. + +Resources are also associated to a type (e.g. a Linux host, +a Tap device on PlanetLab, an application running on a Linux host, etc). +Different types of resources expose different attributes and traces +and can be connected to other specific types (e.g. A resource representing +a wireless channel can have an attribute SSID and be connected to a +Linux interface but not directly to a Linux host resource) +Figure \ref{fig:intro_resources} exemplifies this concept. + +There are two different types of connections between resources, the +first one is used to define the \emph{topology graph} of the experiment. +This graph provides information about which resources will interact +with which other resources during the experiment +(e.g. application A should run in host B, and host B will be connected +to wireless channel D through a network interface C). +Figure \ref{fig:intro_topo_graph} shows a representation of the concept of +topology graph to describe the an experiment. + +\begin{figure}[h] + \centering + \includegraphics[width=0.8\textwidth]{intro_topo_graph} + \caption{A topology graph representation of an abstract experiment} + \label{fig:intro_topo_graph} +\end{figure} + +The second type of connections (called conditions to differentiate them +from the first type) specifies the \emph{dependencies graph}. +This graph is optional and imposes constraints on the experiment +workflow, that is the order in which different events occur during the +experiment. For instance, as depicted in Figure \ref{fig:intro_dependencies_graph} +a condition on the experiment could specify that +a server application has to start before a client application does, or that +an network interface needs to be stopped (go down) at a certain time after +the beginning of the experiment. + +\begin{figure}[h] + \centering + \includegraphics[width=0.8\textwidth]{intro_dependencies_graph} + \caption{A dependencies graph representation involving two applications + resources in an experiment} + \label{fig:intro_dependencies_graph} +\end{figure} + +It is important to note, that the \emph{topology graph} also defines +implicit and compulsory workflow constraints +(e.g. if an application is \emph{topologically} connected to a host, +the host will always need to be up and running before an application +can run on it). +The difference is that the \emph{dependency graph} adds complementary +constraints specified by the user, related to the behavior of the +experiment. + +This technique for modeling experiments is generic enough that can be used +to describe experiments involving resources from any experimentation +environment (i.e. testbed, simulator, emulator, etc). However, it +does not provide by itself any information about how to actually deploy +and run an experiment using concrete resources. + + +\section{Experiment Life Cycle} + +The Experiment Description by itself is not enough to conduct an experiment. +In order to run an experiment it is necessary to translate the description +into concrete actions and to perform these actions on the specific resources +taking part of the experiment. NEPI does this for the user in an automated +manner. + +\begin{figure}[h] + \centering + \includegraphics[width=0.8\textwidth]{intro_life_cycle} + \caption{Common stages of a network experiment life cycle} + \label{fig:intro_life_cycle} +\end{figure} + +Given that different resources will require performing actions in +different ways (e.g. deploying an application on +a Linux machine is different than deploying a mobile wireless robot), +NEPI abstracts the life cycle of resources into common stages associated +to generic actions, and allows to plug-in different implementation of +these actions for different types of resources. +Figure \ref{fig:intro_life_cycle} shows the three +main stages of the network experiment life cycle, \emph{Deployment}, +\emph{Control} and \emph{Result (collection)}, and the actions that are +involved in each of them. + +\begin{figure}[h] + \centering + \includegraphics[width=\textwidth]{intro_state_transitions} + \caption{Resources state transitions} + \label{fig:intro_state_transitions} +\end{figure} + +In order to be able to control different types of resources in +a uniform way, NEPI assigns a generic state to each of these +actions and expects all resources to follow the same set of +state transitions during the experiment life. The states and +state transitions are depicted in Figure +\ref{fig:intro_state_transitions}. + +It is important to note that NEPI does not require these states +to be globally synchronized for all resources (e.g. resources +are not required to be all ready or started at the same time). +NEPI does not even require all resources to be declared and known +at the beginning of the experiment, making it possible to use +an \emph{interactive deployment} mode, where new resources can de +declared and deployed on the fly, according to the experiment needs. +This interactive mode can be useful to run experiments with the +purpose of exploring a new technology, or to use NEPI as a adaptive +experimentation tool, that could change an experiment according to +changing external conditions or measurements. + +\section{Resource Management: The EC \& The RMs} + +The Experiment Controller (EC) is the entity that is responsible for +translating the Experiment Description into a running experiment. +It holds the \emph{topology} and \emph{dependencies} graphs, and it +exposes a generic experiment control API that the user can +invoke to deploy experiments, control resources and collect results. + +\begin{figure}[h] + \centering + \includegraphics[width=\textwidth]{intro_ec} + \caption{User interacting with the Experiment Controller} + \label{fig:intro_ec} +\end{figure} + +As shown in Figure \ref{fig:intro_ec}, the user declares the resources and +their dependencies directly with the EC. +When the user requests the EC to deploy a certain resource or a +group of resources, the EC will take care of performing all the necessary +actions without further user intervention, including the sequencing of +actions to respect user defined and topology specific dependencies, +through internal scheduling mechanisms. + +The EC is a generic entity responsible for the global orchestration of +the experiment. As such, it abstracts itself from the details of how to +control concrete resources and relies on other entities called Resource Managers +(RM)s to perform resource specific actions. + +For each resource that the user registers in the \emph{topology graph}, the EC +will instantiate a RM of a corresponding type. A RM is a resource specific +controller and different types of resources require a different type of +RM, specifically adapted to manage them. + +The EC communicates with the RMs through a well defined API that exposes +the necessary methods (actions) to achieve all the state transitions defined by the +common resource life-cycle. Each type of RM must provide a specific implementation +for each action and ensure that the correct state transition has been achieved +for the resource (e.g. upon invocation of the START action, the RM must take +the necessary steps to start the resource and set itself to state STARTED). +This decoupling between the EC and the RMs makes it possible to extend the +control capabilities of NEPI to arbitrary resources, as long as a RM can be +implemented to support it. + +As an example, a testbed \emph{X} could allow to control host resources using a +certain API X, which could be accessed via HTTP, XMLRPC, or via any other protocol. +In order to allow NEPI to run experiments using this type of resource, it would +suffice to create a new RM of type host X, which extends the common RM API, and +implements the API X to manage the resources. + +Figure \ref{fig:intro_resource_management} illustrates how the user, the EC, +the RMs and the resources collaborate together to run an experiment. + +\begin{figure}[h] + \centering + \includegraphics[width=\textwidth]{intro_resource_management} + \caption{Resource management in NEPI} + \label{fig:intro_resource_management} +\end{figure} diff --git a/doc/user_manual/release_cycle.tex b/doc/user_manual/release_cycle.tex new file mode 100644 index 00000000..7b628d2b --- /dev/null +++ b/doc/user_manual/release_cycle.tex @@ -0,0 +1,25 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%TODO: Explain how to create patch + +TODO diff --git a/doc/user_manual/rm_internals.tex b/doc/user_manual/rm_internals.tex new file mode 100644 index 00000000..575911b2 --- /dev/null +++ b/doc/user_manual/rm_internals.tex @@ -0,0 +1,37 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%ResourceManger internals + +\begin{itemize} + \item States + \item Actions + \item RM API (the schedule methods and the internal methods do\_blah, the states and times are recorded) + \item failtrap + \item RM inheritance + \item init\_copy + \item Adding new attributes + \item Traces and the trace method + \item The start\_with\_condition method and the conditions structure + \item How to enforce internal conditions by re-scheduling +\end{itemize} + diff --git a/doc/user_manual/supported_resources.tex b/doc/user_manual/supported_resources.tex new file mode 100644 index 00000000..d9fc8ada --- /dev/null +++ b/doc/user_manual/supported_resources.tex @@ -0,0 +1,53 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{Linux resources} + +\begin{itemize} + \item SSH + \item The directory structure + \item Linux Node (Clean home, etc) + \item The api (run, exceute, x11, etc) + \item Traces and collection + \item Linux Application + \item LinuxPing, LinuxTraceroute, etc + \item CCNx +\end{itemize} + +\section{Planetlab resources} + +\begin{itemize} + \item how to get an account + \item The vsys system + \item python-vsys + \item TAP/TUN/TUNNEL + \item Note on PL inestability + \item differences between PLE and PLC +\end{itemize} + +\section{OMF resources} + +\begin{itemize} + \item available OMF testbeds + \item how to get an account + \item the concept of resource reservation +\end{itemize} diff --git a/doc/user_manual/unit_testing.tex b/doc/user_manual/unit_testing.tex new file mode 100644 index 00000000..96a17414 --- /dev/null +++ b/doc/user_manual/unit_testing.tex @@ -0,0 +1,23 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +TODO diff --git a/doc/user_manual/user_manual.pdf b/doc/user_manual/user_manual.pdf new file mode 100644 index 00000000..7a2b5573 Binary files /dev/null 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 new file mode 100644 index 00000000..7dbf1e9a --- /dev/null +++ b/doc/user_manual/user_manual.tex @@ -0,0 +1,195 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% NEPI, a framework to manage network experiments +% Copyright (C) 2013 INRIA +% +% This program is free software: you can redistribute it and/or modify +% it under the terms of the GNU General Public License as published by +% the Free Software Foundation, either version 3 of the License, or +% (at your option) any later version. +% +% This program is distributed in the hope that it will be useful, +% but WITHOUT ANY WARRANTY; without even the implied warranty of +% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +% GNU General Public License for more details. +% +% You should have received a copy of the GNU General Public License +% along with this program. If not, see . +% +% Author: Alina Quereilhac +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + +%\documentclass[12pt, openright,twoside]{memoir} +%% avoid blank page between chapters with openany +\documentclass[12pt,openany]{memoir} +%% Make margings on even and odd pages equal +\setulmarginsandblock{3cm}{3cm}{*} +\setlrmarginsandblock{3cm}{3cm}{*} +\checkandfixthelayout + +\usepackage[T1]{fontenc} +\usepackage{kpfonts} +\setSingleSpace{1.1} +\SingleSpacing +\usepackage{xcolor,calc} +\definecolor{chaptercolor}{gray}{0.8} + +% helper macros +\newcommand\numlifter[1]{\raisebox{-2cm}[0pt][0pt]{\smash{#1}}} +\newcommand\numindent{\kern37pt} +\newlength\chaptertitleboxheight + +\makechapterstyle{hansen}{ + \renewcommand\printchaptername{\raggedleft} + \renewcommand\printchapternum{% + \begingroup% + \leavevmode% + \chapnumfont% + \strut% + \numlifter{\thechapter}% + \numindent% + \endgroup% + } + \renewcommand*{\printchapternonum}{% + \vphantom{\begingroup% + \leavevmode% + \chapnumfont% + \numlifter{\vphantom{9}}% + \numindent% + \endgroup} + \afterchapternum} + \setlength\midchapskip{0pt} + \setlength\beforechapskip{0.5\baselineskip} + \setlength{\afterchapskip}{3\baselineskip} + \renewcommand\chapnumfont{% + \fontsize{4cm}{0cm}% + \bfseries% + \sffamily% + \color{chaptercolor}% + } + \renewcommand\chaptitlefont{% + \normalfont% + \huge% + \bfseries% + \raggedleft% + }% + \settototalheight\chaptertitleboxheight{% + \parbox{\textwidth}{\chaptitlefont \strut bg\\bg\strut}} + \renewcommand\printchaptertitle[1]{% + \parbox[t][\chaptertitleboxheight][t]{\textwidth}{% + %\microtypesetup{protrusion=false}% add this if you use microtype + \chaptitlefont\strut ##1\strut}% + } +} +\chapterstyle{hansen} + +\usepackage{verbatim} +\usepackage{hyperref} +%% Remove red squares on top of hyperlinks +\hypersetup{% + pdfborder = {0 0 0} + } + +\usepackage{graphicx} +\usepackage{listings} +\usepackage{color} +\usepackage[scaled]{beramono} + +\definecolor{mygreen}{rgb}{0,0.6,0} +\definecolor{mygray}{rgb}{0.5,0.5,0.5} +\definecolor{mymauve}{rgb}{0.58,0,0.82} +\definecolor{mylightgray}{gray}{0.95} + +\lstset{ % + backgroundcolor=\color{mylightgray}, % choose the background color; you must add \usepackage{color} or \usepackage{xcolor} + basicstyle=\footnotesize\ttfamily, % the size of the fonts that are used for the code + breakatwhitespace=false, % sets if automatic breaks should only happen at whitespace + breaklines=true, % sets automatic line breaking + captionpos=b, % sets the caption-position to bottom + commentstyle=\color{mygreen}, % comment style + deletekeywords={...}, % if you want to delete keywords from the given language + escapeinside={\%*}{*)}, % if you want to add LaTeX within your code + extendedchars=true, % lets you use non-ASCII characters; for 8-bits encodings only, does not work with UTF-8 + %frame=single, % adds a frame around the code + keepspaces=true, % keeps spaces in text, useful for keeping indentation of code (possibly needs columns=flexible) + keywordstyle=\color{blue}, % keyword style + language=Python, % the language of the code + morekeywords={*,...}, % if you want to add more keywords to the set + %numbers=left, % where to put the line-numbers; possible values are (none, left, right) + %numbersep=5pt, % how far the line-numbers are from the code + %numberstyle=\tiny\color{mygray}, % the style that is used for the line-numbers + %stepnumber=1, % the step between two line-numbers. If it's 1, each line will be numbered + rulecolor=\color{black}, % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. comments (green here)) + showspaces=false, % show spaces everywhere adding particular underscores; it overrides 'showstringspaces' + showstringspaces=false, % underline spaces within strings only + showtabs=false, % show tabs within strings adding particular underscores + stringstyle=\color{mymauve}, % string literal style + tabsize=2, % sets default tabsize to 2 spaces + title=\lstname % show the filename of files included with \lstinputlisting; also try caption instead of title +} + + +\title{NEPI v3.0 User Manual} +\date{} +\author{} + +\begin{document} + +% clear numbering from first page +\clearpage\maketitle +\thispagestyle{empty} + +\pagebreak +\tableofcontents + +\chapter{FAQ} +\label{faq} +\input{faq.tex} + +\chapter{Getting started} +\label{getting_started} +\input{getting_started.tex} + +\chapter{Introduction to NEPI} +\label{introduction} +\input{introduction.tex} + +\chapter{The ExperimentController API} +\label{ec_api} +\input{ec_api.tex} + +\chapter{Supported resources} +\label{supported_resources} +\input{supported_resources.tex} + +%%\chapter{ExperimentController internals} +%%\label{ec_internals} +%%\input{ec_internals.tex} + +%%\chapter{ResourceManager internals} +%%\label{rm_internals} +%%\input{rm_internals.tex} + +%%\chapter{Extending NEPI: The CCNx case} +%%\label{extending_nepi} +%%\input{extending_nepi.tex} + +\chapter{Debbuging} +\label{debugging} +\input{debugging.tex} + +%%\chapter{Unit testing} +%%\label{unit_testing} +%%\input{unit_testing.tex} + +%%\chapter{Release Cycle} +%%\label{release_cycle} +%%\input{release_cycle.tex} + +%%\chapter{Coding Style} +%%\label{coding_style} +%%\input{coding_style.tex} + +\end{document}