--- /dev/null
+This section aims at providing some information about OMF and its implementation in NEPI. Regarding to OMF itself, this user manual is not the official OMF Documenation and must be considered only as a complement to the official one (https://mytestbed.net/), gathering information collected during few years working with OMF.
+
+\subsection{OMF 5.4 vs OMF 6}
+
+Two versions really different of OMF exists and are already deployed in different testbed. OMF 5.4.x is the oldest one and is not anymore under development. Many testbed use this version in their testbed and start step by step to migrate towards OMF 6. This latter is still under development. Some projects, as Fed4Fire, want to use this technology and put many efforts to deploy this new version.
+
+Among the main differences between these two versions, we can noticed :
+\begin{itemize}
+\item OMF 5.4 use a Resource Controller (RC) that handles messages received throught XMPP. OMF 6 use a Resource Proxy (RP) that allow the posibility to create a Resource Controller to control an entity. So There is only one RP but one RC for each entity involved in the experiment.
+\item The message protocol in OMF 5.4 use some specific keywords to create action, or configure data. It is not really flexible and was not prepared for extension. In OMF6, the protocol is well-defined and highly thought to be extensible as mush as possible. It is base on 5 routines that allow any action. This protocol is called FRCP.
+\item Both of them use OEDL as description language.
+\end{itemize}
+
+\subsection{Available OMF Testbed}
+
+This subsection gather some information about well-known OMF Testbed. This list is not exhaustive and many others OMF-testbeds are under deployment.
+
+\subsubsection{Nicta Testbed : Norbit}
+
+Nicta is the main developers institute of OMF. It has also its own testbed, called Norbit, containing around 40 nodes deployed on a building. These nodes are usually ALIX nodes, with small power consumption and CPU performance.
+More details can be found on their website :
+http://mytestbed.net/projects/1/wiki/OMFatNICTA
+
+\subsubsection{Nitos Testbed : NitLab}
+
+Nitos is deployed in Greece on a 4th, 5th and 6th floor of a building in the city. Different nodes are deployed as commell or diskless node, but some new powerful nodes will be deployed soon, called Icarus Node, with high CPU performance. The total number of nodes deployed on this testbed is around 50.
+
+More details can be found on their website :
+http://nitlab.inf.uth.gr/NITlab/
+
+\subsubsection{iMinds Testbed : W-ilab.t}
+
+iMinds is deployed in Belgium. The W-ilab.t testbed gather more that one testbed. Among them, there is one in Zwijnaarde that use OMF. Around 60 nodes are deployed on the ceil of their building and one room is reserved for mobile nodes ( using Roomba ). Around 10 mobile nodes will be deployed and operationnal in 2014.
+
+More details can be found on their website :
+http://www.crew-project.eu/portal/wilab/basic-tutorial-your-first-experiment-w-ilabt
+
+\subsection{How to get an Account}
+
+Usually, the creation of the account need to be asked by email. Specific instructions are provided below about how to request an account :
+\begin{itemize}
+\item Nicta : Ask thierry.rakotoarivelo@nicta.com.au
+\item Nitos : Use your onelab account (if you already have one) or create a new account directly on their website
+( http://nitlab.inf.uth.gr/NITlab/index.php/testbed )
+\item iMinds : You need a VPN access and a Testbed Account. For the VPN Account, ask stefan.bouckaert@iminds.be and check the tips below to install OpenVPN. For the Testbed Account, ask pieter.becue@intec.ugent.be or directly on the w-iLabt.t web interface (It will required the VPN Access)
+\end{itemize}
+
+\subsubsection{Tips about OpenVPN}
+
+To install OpenVPN from the sources, be sure that lib-lzo and lib-ssl are installed. If not, ./configure will allow to disable it by doing --disable-lzo or --disable-crypto. You should NOT do it unless you know what you are doing.
+To install the components, follow these commands :
+\begin{itemize}
+\item For Lzo :
+\begin{itemize}
+\item sudo apt-get install liblzo2-2 liblzo2-dev
+\item OR from the source (http://www.oberhumer.com/opensource/lzo/\#download) following these instructions
+(http://www.linuxfromscratch.org/blfs/view/6.3/general/LZO.html)
+\end{itemize}
+\item For Openssl : sudo apt-get install libssl-dev
+\end{itemize}
+Finally, You will have to launch OpenVPN using the credentials you received from the testbed owner. The command will be something like :
+sudo openvpn file.ovpn
+
+\subsection{How to reserve some nodes}
+
+After creating your account, you need to reserve some nodes to deploy your experiment on them. Different policies are used until now but it will move toward a common policy called Broker.
+
+This is the list of the current reservation method :
+\begin{itemize}
+\item Nicta : Use google calendar for a gentleman's agreement. Add your reservations directly in the google calendar. This functionality is enable only after asking the Nicta team to add your Gmail address.
+\item Nitos : While logged into the website, you can use the Nitos Scheduler to reserve some nodes and some channels for a maximum period of 4hours
+\item iMinds : Reserve your experiment on their website
+http://boss.wilab2.ilabt.iminds.be/reservation/. Your experiment should be swapped in automatically. If it is not the case, turn on your experiment on their website
+(https://www.wilab2.ilabt.iminds.be/) and the provisionning will be done by their tools. The number of nodes you required through the interfaces will be allocated for you with the image you declare (default image is Ubuntu 12.04 if nothing has been specified)
+\end{itemize}
+
+
+\subsection{XMPP}
+
+The default communication layer used in OMF is XMPP. Xmpp is a PubSub communication system based on group. A group respresent a set of resource that can subscribe to this group. Each resource can then publish to this group and consequently send some messages to each resource that also subscribed.
+Even if AMQP is supported by OMF, NEPI support only XMPP as it is mainly deployed on all the testbed.
+
+The implementation of the XMPP client is based on the library SleekXmpp. Each method has been overwritten to fit the requirement we need to OMF.
+
+Finally, There is an OMF XMPP Factory that allow for each OMF Resource Manager to share the same Xmpp Client. Based on some credentials as the user or the password, the OMF XMPP factory store the different XMPP Client. When an OMF RM wants to communicate, it ask the Factory to retrieve one XMPP Client using the credentials it has or to create one if it doesn't exists. The factory store the number of RM that use each XMPP Client and delete it when no RM use it.
+
+
+
+
+
+
+
+
+
--- /dev/null
+The Planetlab node resource inherits every feature of the Linux node, but adds the ability to choose for your experiment, healthy nodes from the Planetlab testbed. By healthy we mean alive nodes, accessible via ssh using your authentication information, with a checked filesystem in order to discard future problems during run-time.
+
+\subsection{How to get an account}
+
+ \subsubsection{Register}
+
+If you want to use nodes from the Planetlab testbed, first you need to have an account, if you don't have one, you can register on the planetlab europe portal www.planet-lab.eu (see Create an account).
+
+ \subsubsection{Add your account to a Slice}
+
+Then, in order to have access to the nodes needed for your experiment, you will need a slice. A slice is a subset of the planetlab resources, capable of running an experiment. Usually, once you own an account, you ask someone from your institue for a slice creation. The granted person ( called PI ) can then create a slice for you or associate you to an already existing slice.
+
+ \subsubsection{Differences between PLE and PLC}
+
+Different instamces of PlanetLab exist like PlanetLab Central, PlanetLab Europe, PlanetLab Japan,... PlanetLab Europe (PLE) is the European portion of the publicly available PlanetLab (PLC) testbed. They main operational difference is related to credentials. If the testbed that issues the credentials is the european testbed, then for the PlanetLab Europe nodes the user can query more status information. Having more information can be beneficial when defining selection filters for the nodes. Anyway, PLE and PLC are federated, meaning the discovery and provisioning is always possible.
+
+\subsection{The Planetlab Node RM}
+
+In order for NEPI to select healthy nodes for your experiment and add them to your slice, it is necessary to set three attributes after resource registration : username, pluser and plpassword. username is the name to ssh login in your nodes, for Planetlab testbed it will always be your slice
+name. pluser and plpassword are the user and password used for authenticate yourself in the Planetlab web page (www.planet-lab.eu). For example, when registering a Planetlab node for your experiment, the
+experiment description will look a lot like this:
+\begin{lstlisting}[language=Python]
+node = ec.register_resource("PlanetlabNode")
+ec.set(node, "username", "institute_project")
+ec.set(node, "pluser", "john.doe@institute.edu")
+ec.set(node, "plpassword", "guessit")
+\end{lstlisting}
+When you log in with your credential to the Planetlab testbed portal (www.planet-lab.eu), you should be able to see the slices associated to your user as well as the set of nodes currently in your slices, and all the nodes provided by the testbed. Moreover, the web page allows the user to browse these resources and find out more characteristics about them. However, using the web site is not really convenient for large experiment involving hundreds of nodes. NEPI can do this job for you.
+
+The portal retrieves the node's information by quering a service called MyPLC, NEPI queries the same service to efficiently select the most suitable nodes for the experiment. The user and password to query this service are the ones introduced before as pluser, and plpassword.
+
+NEPI allows the user to filter among the Planetlab nodes according to different criterias, aiming to select a specific set of nodes for the experiment. For example, one experiment could only require nodes with OS Fedora 14, so the user should use the OS filter available for the Planetlab node resource when describing the node.
+
+Current list of filters available :
+\begin{itemize}
+ \item city
+ \item country
+ \item region
+ \item architecture
+ \item operating\_system
+ \item min\_reliability
+ \item max\_reliability
+ \item min\_bandwidth
+ \item max\_bandwidth
+ \item min\_load
+ \item max\_load
+ \item min\_cpu
+ \item max\_cpu
+\end{itemize}
+
+We have already mentionned that, in order to use MyPLC service, it is necessary to set the attributes pluser and plpassword. Filters are also represented by attributes and can be set by the user. Different type of filter exist, each one corresponding to a specific kind of value (String, Enumerate, ...). For each attribute, more information can be found in the help associated to this attribute as well as in its definition.
+
+For example, for the attribute operating system, one can find the help, type, values allowed, etc. in its definition (src/nepi/resources/planetlab/node.py):
+\begin{lstlisting}[language=Python]
+operating_system = Attribute("operatingSystem",
+ "Constraint operating system during resource discovery.",
+ type = Types.Enumerate,
+ allowed = ["f8",
+ "f12",
+ "f14",
+ "centos",
+ "other"],
+ flags = Flags.Filter)
+\end{lstlisting}
+Now we know how to add a filter to the node description:
+\begin{lstlisting}[language=Python]
+ node = ec.register_resource("PlanetlabNode??")
+ ec.set(node, "username", "institute_project")
+ ec.set(node, "pluser", "jhon.doe@institute.edu")
+ ec.set(node, "plpassword", "guessit")
+ ec.set(node, "operatingSystem", "f14")
+\end{lstlisting}
+In case of more filters, an AND between the filters will be applied:
+
+\begin{lstlisting}[language=Python]
+ node = ec.register_resource("PlanetlabNode??")
+ ec.set(node, "username", "institute_project")
+ ec.set(node, "pluser", "jhon.doe@institute.edu")
+ ec.set(node, "plpassword", "guessit")
+ ec.set(node, "operatingSystem", "f14")
+ ec.set(node, "minCpu", 50)
+\end{lstlisting}
+
+Note that minCpu = 50 means that at least 50\% of the CPU has to be free in the node, to make the node suitable for the experiment.
+
+
+\subsubsection{The hostname attribute}
+
+Another attribute that the user can define for the node is the hostname. This attribute has priority over the others filters. When the experiment needs more than one node, it is necessary to register conditions in order to ensure that the nodes identified by its hostname are selected before the others nodes (the ones identified by filters or just not identified at all).
+
+For example, imagine we need two nodes for our experiment :
+Current list of filters available :
+\begin{itemize}
+ \item For one of them, we are completly sure that we want to use a specific one, so we identify it by its hostname
+ \item For the other one, we just want to fulfill the restriction of OS fedora 8 and country France.
+\end{itemize}
+
+In this case, our experiment description will look like this:
+\begin{lstlisting}[language=Python]
+node1 = ec.register_resource("PlanetlabNode")
+ec.set(node1, "username", "institute_project")
+ec.set(node1, "pluser", "john.doe@institute.edu")
+ec.set(node1, "plpassword", "guessit")
+ec.set(node1, "hostname", "planetlab2.utt.fr")
+## planetlab2.utt.fr is the specific node we want to use
+
+node2 = ec.register_resource("PlanetlabNode")
+ec.set(node2, "username", "institute_project")
+ec.set(node2, "pluser", "john.doe@institute.edu")
+ec.set(node2, "plpassword", "guessit")
+ec.set(node2, "operatingSystem", "f8")
+ec.set(node2, "country", "France")
+\end{lstlisting}
+The nodes that are identified by their hostnames have to be provisioned before the rest of the nodes. This assures that no other resource will use the identified node even if the constraints matchs. Meaning that, even if the host "planetlab2.utt.fr" fulfills the conditions OS fedora 8 and country France, the node2 resource should not select from the planetlab testbed "planetlab2.utt.fr", the node1 must select it. We can enforce this to happen using the register\_condition method of the ec. Therefore, after registering the node and setting its attributes, we need to add this line:
+\begin{lstlisting}[language=Python]
+ec.register_condition(node2,ResourceAction.DEPLOY, node1, ResourceState.PROVISIONED)
+\end{lstlisting}
+For a better example on how to use filters and register conditions, there is the ping experiment example (examples/planetlab/ping\_experiment.py). In this example we define 5 nodes, and 4 ping applications running in 4 of the nodes, with the 5th one as destination. Then we collect the traces in our local machine.
+
+
+\subsubsection{Persist blacklisted nodes}
+
+PlanetLab nodes may fail for different reasons, ssh authentication failure, file system corrupted, nodes unreachable, between others. Moreover, the mal functioning nodes can vary from one experiment run to the next one. In NEPI there is the ability to register these mal functioning nodes in order run the experiment in a more efficient way. Also, this information can be use to evaluate the performance of the experiment and the nodes themselves.
+
+The PlanetlabNode resource, is instantiated for each Planetlab node defined in the experiment. The node discovery and provisioning occurs in parallel for every node defined, so a list of the nodes failures is needed while deploying, in order to avoid to repeat the provision of mal functioning nodes. This list of blacklisted nodes during the experiment, can be saved and maintain for following run of the same experiment or others experiments. This list it is called blacklist. Moreover, the nodes in the blacklist in the moment the experiment is started, can be use to directly discard from the node discover and provision the unwanted nodes.
+
+There is an attribute available for this matter, is called 'persist\_blacklist' and is a global attribute, meaning that if set, is set for every resource of type PlanetlabNode.
+The blacklist file is stored in ~/.nepi/plblacklist.txt.
+
+Example on how to use the attribute:
+
+Two Planetlab nodes that read from the blacklist at the beginning of the experiment, and write new blacklisted nodes (if any) at the end.
+\begin{lstlisting}[language=Python]
+node1 = ec.register_resource("PlanetlabNode")
+ec.set(node1, "username", username)
+ec.set(node1, "pluser", pl_user)
+ec.set(node1, "plpassword", pl_password)
+ec.set(node1, "cleanHome", True)
+ec.set(node1, "cleanProcesses", True)
+
+node2 = ec.register_resource("PlanetlabNode")
+ec.set(node2, "username", username)
+ec.set(node2, "pluser", pl_user)
+ec.set(node2, "plpassword", pl_password)
+ec.set(node2, "cleanHome", True)
+ec.set(node2, "cleanProcesses", True)
+
+ec.set_global('PlanetlabNode', 'persist_blacklist', True)
+\end{lstlisting}
+The attribute can be retrieved with the method get\_global :
+\begin{lstlisting}[language=Python]
+ec.get_global('PlanetlabNode', 'persist_blacklist').
+\end{lstlisting}
+\subsection{SFA Support}
+
+\subsubsection{Why using SFA for discovery and provision of resources in NEPI?}
+
+In order to be able to reserve resources for cross testbed experiments without having to deal with different types of credentials, is important that testbed adopt the SFA interface and the users have at least one set of credentials in one testbed. With the SFA user credential, slice credential and authority credential, the user can list resources, allocate them, provision them, delete them from his slice, plus, add or remove slices when is allowed, in any SFA compliant testbed that trust each others registry. The last assures an uniform control plane operation layer (discovery, reservation, and provisioning) for every type of resource in any SFA compliant testbed.
+
+NEPI developed the appropriate framework to be able to solve control plane operations through SFA. Based on the sfi client, NEPI developed an API that implement for the user, the corresponding SFA AM calls to handle the first steps of the experiment lifecycle. This is transparent for the user, who doesn't need to deal with SFA calls specifics, or understanding RSpecs (Resource specification). Moreover, NEPI implemented functions to assist in the selection of a set of reservable resources.
+
+The use of SFA then, requires that the user installs the sfi client (version\_tag="3.1-4"), you can check http://svn.planet-lab.org/wiki/SFATutorial\#SFATutorial for more information.
+
+\subsubsection{SFA in PlanetLab}
+
+This should not add complexity for the user, for example, for the Planetlab node, the experiment description is very similar:
+\begin{lstlisting}[language=Python]
+from nepi.execution.ec import ExperimentController
+import os
+
+# Create the EC
+exp_id = "sfa_test"
+ec = ExperimentController(exp_id)
+
+username = os.environ.get('SFA_SLICE') --- for example 'inria_lguevgeo'
+sfauser = os.environ.get('SFA_USER') --- for example 'ple.inria.lucia_guevgeozian_odizzio'
+sfaPrivateKey = os.environ.get('SFA_PK') --- for example '/home/.sfi/lucia_guevgeozian_odizzio.pkey'
+
+node1 = ec.register_resource("PlanetlabSfaNode")
+ec.set(node1, "hostname", 'planetlab1.cs.vu.nl')
+ec.set(node1, "username", username)
+ec.set(node1, "sfauser", sfauser)
+ec.set(node1, "sfaPrivateKey", sfaPrivateKey)
+ec.set(node1, "cleanHome", True)
+ec.set(node1, "cleanProcesses", True)
+\end{lstlisting}
+\subsubsection{SFA with iMinds Testbed (w-iLab.t)}
+
+The control and management software running in w-iLab.t is OMF 6, but its resources can be discover and provisioned using SFA, the experiment description for the WilabtSfaNode in NEPI is similar to the one in PlanetlabNode. Below is an example :
+\begin{lstlisting}[language=Python]
+from nepi.execution.ec import ExperimentController
+import os
+
+# Create the EC
+exp_id = "sfa_test"
+ec = ExperimentController(exp_id)
+
+slicename = 'ple.inria.lguevgeo'
+sfauser = os.environ.get('SFA_USER')
+sfaPrivateKey = os.environ.get('SFA_PK')
+
+# nodes
+node1 = ec.register_resource("WilabtSfaNode")
+ec.set(node1, "hostname", 'zotacM20')
+ec.set(node1, "slicename", slicename)
+ec.set(node1, "sfauser", sfauser)
+ec.set(node1, "sfaPrivateKey", sfaPrivateKey)
+ec.set(node1, "gatewayUser", "nepi")
+ec.set(node1, "gateway", "bastion.test.iminds.be")
+ec.set(node1, "cleanHome", True)
+ec.set(node1, "cleanProcesses", True)
+\end{lstlisting}
+
+Note that the w-iLab.t testbed is a private testbed, and resources can be accessed only through a gateway. The node description must have two attributes defined as gatewayUser and gateway. The appropriate ssh key settings in the gateway must be pre-arranged with the testbed administrators, in order to enable the ssh access.
+
+The gateway feature is not only possible for the w-iLab.t testbed, but for any testbed that allow ssh key authentication. The ability to store the blacklisted nodes is also possible for the w-iLab.t testbed.
+
+
+
+
+\subsection{The vsys system}
+ TO DO
+
+ \subsubsection{Python Vsys}
+ TO DO
+
+ \subsubsection{TAP/TUN/TUNNEL}
+ TO DO
+
+
# Create and Configure the Nodes
node1 = ec.register_resource("OMFNode")
-ec.set(node1, 'hostname', 'servernode.vlc.nepi.wilab2.ilabt.iminds.be')
+ec.set(node1, 'hostname', 'servernode.nepivlcexperiment.nepi.wilab2.ilabt.iminds.be')
ec.set(node1, 'xmppServer', "xmpp.ilabt.iminds.be")
ec.set(node1, 'xmppUser', "nepi")
ec.set(node1, 'xmppPort', "5222")
ec.set(iface1, 'ip', "192.168.0.1/24")
node2 = ec.register_resource("OMFNode")
-ec.set(node2, 'hostname', 'clientnode.vlc.nepi.wilab2.ilabt.iminds.be')
+ec.set(node2, 'hostname', 'client1node.nepivlcexperiment.nepi.wilab2.ilabt.iminds.be')
ec.set(node2, 'xmppServer', "xmpp.ilabt.iminds.be")
ec.set(node2, 'xmppUser', "nepi")
ec.set(node2, 'xmppPort', "5222")
ec.set(iface2, 'essid', "vlc")
ec.set(iface2, 'ip', "192.168.0.2/24")
+node3 = ec.register_resource("OMFNode")
+ec.set(node3, 'hostname', 'client2node.nepivlcexperiment.nepi.wilab2.ilabt.iminds.be')
+ec.set(node3, 'xmppServer', "xmpp.ilabt.iminds.be")
+ec.set(node3, 'xmppUser', "nepi")
+ec.set(node3, 'xmppPort', "5222")
+ec.set(node3, 'xmppPassword', "1234")
+
+iface3 = ec.register_resource("OMFWifiInterface")
+ec.set(iface3, 'name', 'wlan0')
+ec.set(iface3, 'mode', "adhoc")
+ec.set(iface3, 'hw_mode', "g")
+ec.set(iface3, 'essid', "vlc")
+ec.set(iface3, 'ip', "192.168.0.3/24")
+
chan = ec.register_resource("OMFChannel")
ec.set(chan, 'channel', "6")
# Create and Configure the Application
app1 = ec.register_resource("OMFApplication")
-ec.set(app1, 'command', "DISPLAY=localhost:10.0 XAUTHORITY=/root/.Xauthority /root/vlc/vlc-1.1.13/cvlc /root/10-by-p0d.avi --sout '#rtp{dst=192.168.0.2,port=1234,mux=ts}'")
+ec.set(app1, 'command', "DISPLAY=localhost:10.0 XAUTHORITY=/root/.Xauthority /root/vlc/vlc-1.1.13/cvlc /root/10-by-p0d.avi --sout '#duplicate{dst=rtp{dst=192.168.0.2,port=1234,mux=ts},dst=rtp{dst=192.168.0.3,port=1234,mux=ts}}'")
app2 = ec.register_resource("OMFApplication")
ec.set(app2, 'command', "DISPLAY=localhost:10.0 XAUTHORITY=/root/.Xauthority /root/vlc/vlc-1.1.13/cvlc rtp://192.168.0.2:1234")
+app3 = ec.register_resource("OMFApplication")
+ec.set(app3, 'command', "DISPLAY=localhost:10.0 XAUTHORITY=/root/.Xauthority /root/vlc/vlc-1.1.13/cvlc rtp://192.168.0.3:1234")
+
+
+ "echo -e 'new TEST broadcast enabled loop\\n"\
+ "setup TEST input %s\\n"\
+ "setup TEST output #rtp{mux=ts,sdp=rtsp://0.0.0.0:8554/TEST}\\n\\n"\
+ "new test_sched schedule enabled\\n"\
+ "setup test_sched append control TEST play' > ${SOURCES}/VOD.vlm" % mv)
+
+
# Connection
ec.register_connection(iface1, node1)
ec.register_connection(iface2, node2)
+ec.register_connection(iface3, node3)
ec.register_connection(iface1, chan)
ec.register_connection(iface2, chan)
+ec.register_connection(iface3, chan)
ec.register_connection(app1, node1)
ec.register_connection(app2, node2)
+ec.register_connection(app3, node3)
-ec.register_condition([app2], ResourceAction.START, app1, ResourceState.STARTED , "4s")
-ec.register_condition([app1,app2], ResourceAction.STOP, app2, ResourceState.STARTED , "30s")
+ec.register_condition([app2,app3], ResourceAction.START, app1, ResourceState.STARTED , "4s")
+ec.register_condition([app1,app2,app3], ResourceAction.STOP, [app2,app3], ResourceState.STARTED , "30s")
# Deploy
ec.deploy()
-ec.wait_finished([app1,app2])
+ec.wait_finished([app1,app2,app3])
# Stop Experiment
ec.shutdown()
git://git.onelab.eu / nepi.git / commitdiff