% !TEX encoding = IsoLatin

The physical infrastructure needs to be modelized inside the tool to have a clear view of how physical nodes, virtual switches and virtual machines are deployed in the environment. With this model all the physical parameters needed by the tool (e.g. IP addresses, usernames, virtual switch identifiers) are stored inside the respective objects.
Every component of the deployment contains a rule dispatcher that is called every time a rule needs to be injected into the device.

\subsection{Architecture}


The model is represented by the package \code{it.polito.policyorchestration.impl.topology.physical} and contains an abstract class that represents the filtering points in the infrastructure, extended by several sub-classes.


\begin{itemize}
	\item \code{class Deployment}: it contains all the physical hosts and represents the infrastructure which the tool is running on. One or more virtual switch are stored inside \code{PhysicalHost} object, and every virtual switch contains a list of \code{ServiceNode} objects. A \code{ServiceNode} is an object that represents the infrastructure element which contains one or more services (e.g. VirtualMachines, POD).   A deployment is characterized by a Virtual Infrastructure Manager (VIM) (e.g. OpenStack, Kubernetes, etc.). The \code{Deployment} object has the following methods:
	
	\begin{itemize}
		\item \code{public LinkedList<PhysicalHost> getPhysicalHostList()}\newline
		it returns the list of \code{PhysicalHost} objects loaded in the deployment;
		
		\item \code{public PhysicalHost searchPhysicalHost(String ip)}\newline
		it returns the physical host with the given IP address, or \code{null} if the host is not present in the deployment;
		
		\item \code{public LinkedList<VirtualSwitch> getVirtualSwitches()}\newline
		it returns the list of \code{VirtualSwitch} objects loaded in the deployment;
		
		\item \code{public VirtualSwitch searchVirtualSwitch(String label)}\newline
		it returns the virtual switch with the given \textit{datapath-id} (label), or \code{null} if the virtual switch is not present in the deployment;
		
		\item \code{public LinkedList<ServiceNode> getServiceNodes()}\newline
		it returns the list of \code{ServiceNode} objects loaded in the deployment;
		
		\item \code{public ServiceNode searchServiceNode(String ip)}\newline
		it returns the service node with given IP address, or \code{null} if the service node is not present in the deployment;
		
		\item \code{public ServiceNode removeServiceNode(String ip)}\newline
		it removes the service node with given IP address from the the deployment, it returns the removed service node, or \code{null} if the service node is not present in the deployment;
		
		\item \code{public void setFloodlightRuleDispatcher(FlowDispatcher dispatcher)}\newline
		it sets, for each virtual switch, the Floodlight flow dispatcher module to inject OpenFlow flows;
		
		\item \code{public void initializeIptables()}\newline
		it initialize, for each physical node and service node, the Iptables chain where rules will be injected after distribution process;
		
		\item \code{public void cleanup()}\newline
		it removes, for each physical node and service node, the Iptables rules injected by the tool;
		
		\item\code{public void resetFlags()}\newline
		it resets the \code{isExcluded} and \code{isMiddlebox} flags of the \code{FilteringPoints} that compose the deployment;
		
		\item \code{public LinkedList<FilteringPoint> getFilteringPoints()}\newline
		it returns the list of \code{FilteringPoints} that compose the deployment.
		
	\end{itemize} 
	
	\item \code{abstract class FilteringPoint}: this class is an abstract class, it represents a device in which rules can be inserted. It contains all the variables that are in common between all the filtering points of the environment.
	The shared variables are:
	
	\begin{itemize}
		\item \code{private String identifier}\newline
		it is the unique identifier of the filtering point, it can be an IP address for \code{ServiceNode} and \code{PhysicalHost} objects, or it can be the \textit{Datapath-id} of a \code{VirtualSwitch};
		
		\item \code{private PerformanceTool performance}\newline
		it is the performance tool used to compute the performance rating of the filtering point, according to the number of rule that will be injected on it. The performance rating is used by the distribution tool to find the proper device to inject rules;
		
		\item \code{private boolean isExcluded}\newline
		it indicates if the filtering points is excluded from the rule distribution process;

		\item \code{private LinkedList<GenericRule> ruleList}\newline
		it contains the list of rules loaded into the device;
		
		\item \code{private Action defalutAction}\newline
		it represents the default action of the filtering point, it is set based on the entity policy default action;

	\end{itemize}

	\code{FilteringPoint class}, other than default getters and setters, has the following methods:
	\begin{itemize}
		\item \code{LinkedList<GenericRule> addRuleList(LinkedList<GenericRule> ruleList)}\newline
		it add all the of the list passed as parameters to the object' rule list. If the number of rule exceed the maximum number that the physical host can support, the maximum number of rules will be inserted. This methods returns \code{null} if all rules were inserted correctly, otherwise it return a list containing the exceeding rules;
		
		\item \code{public void addRule(GenericRule rule)}\newline
		it adds a single rule to the object rule list;
		
		\item \code{public void printInjectableRules()}\newline
		it prints all the rules that are loaded inside the object;
		
		\item \code{public abstract void injectRules()}\newline
		it starts the rule injection process, the rule injection process is different accordingly to the filtering point type.
		
		\item \code{public int compareTo(FilteringPoint fp)}\newline
		it overrides the default comparator for \code{FilteringPoint} objects, the result depends of the performance rating given by the performance tool;
			
	\end{itemize} 

	This class is extended by three classes that represent the different types of filtering point that the tool supports:
	
	\begin{itemize}
		\item \code{class PhysicalHost}: this class represents a physical host in the infrastructure, it is identified by an IP address. It contains the list of virtual switches, where service nodes will attach to communicate. Each \code{PhysicalHost} has a \code{CommandDispatcher} object that contains all the required libraries to dispatch system commands locally or via SSH connections (e.g. Iptables rule injection commands).
		\code{PhysicalHost} class has the following methods:
		
		\begin{itemize}
				\item \code{public void startup()}\newline
				it initialize the physical host creating a new Iptables chain, where rules will be inserted. After chain creation it inject a rule in existing chains to redirect all traffic to the newly created one;
				
				\item \code{public void shutdown()}\newline
				it removes all injected rules and created chains, restoring previous state;
				
				\item \code{public void addVirtualSwitch(VirtualSwitch sw)}\newline
				it adds a new \code{VirtualSwitch} object to the virtual switch list;
				
				\item \code{public String getSecurityUserName()}\newline
				it returns the username needed to log into the machine from remote hosts. This user must be enabled to run Iptables commands inside the machine.
				
		\end{itemize}
	
		\item \code{class VirtualSwitch}: this class represents a virtual switch where service nodes will be attached. Every virtual switch has a rule dispatcher that will inject filtering rules. In case of OpenFlow switches it uses the Floodlight library to create custom flows and inject them into the switch.
		\code{VirtualSwitch} class has the following methods:	
		
		\begin{itemize}
			\item \code{public void addServiceNode(ServiceNode n)}\newline
			it adds a \code{ServiceNode} object to the virtual switch node list;
			
			\item \code{public ServiceNode removeServiceNode(ServiceNode n)}\newline
			it removes a service node from the list. It returns the removed \code{ServiceNode} object or \code{null} if the object is not present in the list.
			
			\item \code{public VSWTypeElement getType()}\newline
			it returns the type of the virtual switch (e.g. \textit{OVS}, \textit{LINUXBRIDGE}, etc.);
					
		\end{itemize}
	
		\item \code{class ServiceNode}: this class represents the element in the infrastructure in which services are running (e.g. a virtual machine, a Kubernets pod, etc.). It is identified by an IP address and contains the list of services that are running on it. Like physical hosts it contains a \code{CommandDispatcher} object for rule loading.
		\code{ServiceNode} class has the following methods:	
		
		\begin{itemize}
			\item \code{public void startup()}\newline
			it initialize the physical host creating a new Iptables chain, where rules will be inserted. After chain creation it inject a rule in existing chains to redirect all traffic to the newly created one;
			
			\item \code{public void shutdown()}\newline
			it removes all injected rules and created chains, restoring previous state;
			
			\item \code{public void setMiddleBox(boolean isMiddleBox)}\newline
			it marks the service node as a middlebox. A middlebox is a service node capable of traffic routing in which is possible to apply traffic filtering policies;
			
			\item \code{public boolean isMiddleBox()}\newline
			it returns \code{true} if the service node is also a middlebox, \code{false} otherwise;
			
			\item \code{public void addService(Service s)}\newline
			it adds a \code{Service} object to the services list;
			
			\item \code{public void deleteService(String port)}\newline
			it removes a service from the list. It returns the removed \code{Service} object or \code{null} if the object is not present in the list.
			
			\item \code{public NodeTypeElement getType()}\newline
			it returns the type of the service node (e.g. \textit{VM}, \textit{POD}, etc.);
				
		\end{itemize}
		
	\end{itemize}
	\item \code{class PhysicalTopologyFactory}: is the class that manage all physical topology object creation and initialization.
	It can not be instantiated bacause it has private constructor.
	\code{PhysicalTopologyFactory} class has the following methods:	
	
	\begin{itemize}
		\item \code{public static Deployment createDeployment(DeploymentElement dep)}\newline
		it creates a new \code{Deployment} object from a \code{DeploymentElement}. The \code{DeploymentElement} object is the result of XML parsing process done by \code{JAXB Framework}. This method validates the element passed as parameter, using the \code{PhysicalTopologyValidator} class and if the element is correct starts to create the \code{Deployment} adding physical hosts, virtual switches and service nodes. It also instantiate the \code{PerformanceToolFactory} object;
		
		\item \code{public static PhysicalHost createPhysicalHost(Deployment dep, HostElement host, PerformanceToolFactory pf)}\newline
		it creates, after proper element validation, a new \code{PhysicalHost} object from a \code{HostElement};
		
		\item \code{public static VirtualSwitch createVSwitch(Deployment dep, VSwitchElement vswitch, PerformanceToolFactory pf)}\newline
		it creates, after proper element validation, a new \code{VirtualSwitch} object from a \code{VSwitchElement}; 
		
		\item \code{public static ServiceNode createNode(Deployment dep, NodeElement serviceNode, PerformanceToolFactory pf)}\newline
		it creates, after proper element validation, a new \code{ServiceNode} object from a \code{NodeElement};
		
	\end{itemize}

\end{itemize}


\subsection{Modify the tool}
It is possible to extend the \code{FilteringPoint} class adding new types of filtering point. Currently the tool is supporting physical hosts, virtual switches and service nodes as filtering point. It is necessary to implement the \code{void injectRules()} method, defining how rules will be inserted into the defined filtering point. It will be necessary to add the element to the XML and extend the input reading module.
