% !TEX encoding = IsoLatin

\subsection{Command line utilization}

Once the installation procedure is completed, the tool can be used as a standalone program, using directly the \code{jar} archive provided with the command: \code{java -jar baxairco-security.jar}.

The tool needs three configuration files located in the \code{config/} folder:

\begin{itemize}
	\item \code{baxairico.properties} contains all the parameters that can be personalized for tool customization.
	
	\item \code{floodlight.properties} contains all the personalizable parameters for the Floodlight library.
	
	\item \code{logback.xml} allows to personalize logging format and coloring.
\end{itemize}

\subsubsection{baxairico.properties}

This file contains all the customizable parameters supported by the tool:
\begin{itemize}
	\item \code{IPTABLES_CHAIN}: is the name of the Iptables chain created by the tool to inject filtering rules;
	
	\item \code{SSH_KEY_PATH}: is the path were the host SSH keys are stored. This keys needs to be registered on the hosts that compose the cloud infrastructure;
	
	\item \code{REST_PORT}: is the port where the web server will be reachable to perform REST operations;
	
	\item \code{NETWORK_NODE_IP}: is the IP address of the physical node used as network management node (in Openstack);
	
	\item \code{NETWORK_ACCOUNT}: is the account used to get SSH access to the network node;
	
	\item \code{NETWORK_NAMESPACE}: is the namespace name used by the network management node (in OpenStack) to get access to all running instances. It represents a virtual router that interconnects different virtual networks in the deployment;
	
\end{itemize}

Moreover is possible to specify a set of XML and XSD file used as initialization resources for the tool. They represents the macro data structures used in the tool (e.g. \code{Deployment}, \code{Landscape}, \code{Entities}, \code{SelectorTypes}, \code{FilteringPoints}).

\subsubsection{floodlight.properties}

This configuration file allows to configure Floodlight library, customizing listening ports, default action and supported protocols.
Most important field are:
\begin{itemize}
	\item \code{openFlowPort}: it is the port where the controller will be listening for virtual switch connections;
	
	\item \code{workerThreads}: is the number of threads used by Floodlight library;
	
	\item \code{clearTablesOnInitialHandshakeAsMaster}: it enable table erasing when a switch connects to the controller;
	
	\item \code{clearTablesOnEachTransitionToMaster}: it enable table erasing when a switch become active;
	
	\item \code{supportedOpenFlowVersions}: is the list of OpenFlow protocol version supported by the Floodlight controller;	
\end{itemize}

IMPORTANT: for correct operation is necessary that the OpenFlow switches on the OpenStack infrastructure are configured correctly, in particular they must have as controller the host where the tool is running on.

\subsection{JAVA library utilization}

\subsubsection{Orchestration tool}

The tool could be used as a Java library in a project instantiating a \code{PolicyOrchestrationService} object class passing the \code{InfrastructureManager} object to the constructor.

The "start" method begins the distribution process:

\begin{itemize}
	\item 
	{\ttfamily public synchronized void start()}
	
	it allows to check if there are policy anomalies and to perform both resolution and reconciliation between policies and then to distribute security rules based on the optimize model.
	The method is \code{synchronized}, because in case an REST API is used, it offers an easy way to avoid race conditions and all the problems related to multi-threads application.
\end{itemize}

\begin{figure}
\HRule
\begin{lstlisting}[numbers=left,stepnumber=1, language = Java]
// creation of the policy orchestration tool
// infrMgr is an InfrastructureManager instance
PolicyOrchestrationService service = new PolicyOrchestrationService(infrMgr);

// starts the rule distribution
service.start();
\end{lstlisting}
\HRule
\end{figure}

\subsubsection{Distributor tool}

The distributor tool could be used as a Java library in a project instantiating a \code{RuleDistributorTool} object class passing the \code{InfrastructureManager} object to the constructor.
There is no need to start the computation of the optimization model because it is already done during the constructor of the instance.

The "injectRules" method begins the injection process of the rules on the filtering points:

\begin{itemize}
	\item 
	{\ttfamily public void injectRules()}
	
	it allows to inject all the rules, each one on the correct filtering point and with the right order.
\end{itemize}

\begin{figure}
\HRule
\begin{lstlisting}[numbers=left,stepnumber=1, language = Java]
// creation of the rule distributor tool
// infrMgr is an InfrastructureManager instance
RuleDistributorTool ruleDistributor = new RuleDistributorTool(infrMgr);

// starts the rule injection
ruleDistributor.injectRules();
\end{lstlisting}
\HRule
\end{figure}

\subsubsection{Optimization tool}

The optimization tool could be used as a Java library in a project instantiating a \code{OptimizeTool} object class.
It offers differents methods to create boolean or real variables and equations or disequations, which are all listed in \ref{cap:programmerManual} Appendix.

The "minimizeRealVariable" method set the variables, whose value must be the lower possible.
The "calculateModel" method begins the optimization of the model based on the function to be optimize.

\begin{itemize}
		\item 
	{\ttfamily public void minimizeRealVariable(String variable)}
	
	it allows to set the disequation named \code{variable} as the one that the optimzier need to minimized the value.
	
	\item 
	{\ttfamily public void calculateModel()}
	
	it checks if the model is \code{SATISFIABLE}, otherwise it thorws a \code{NotSatisfiableModelException} exception, then it computes the optimization and it sets a value for all the booleans variables created;
\end{itemize}

\begin{figure}
\HRule
\begin{lstlisting}[numbers=left,stepnumber=1, language = Java]
// creation of the optimizer tool
OptimizeTool optimizer = new OptimizeTool();

// creation of booleans variables, equation and disequations
...

// setting the cost function
optimizer.minimizeRealVariable(costFunctionName);

// starts the optimization process
optimizer.calculateModel();
\end{lstlisting}
\HRule
\end{figure}

\subsubsection{Policy tool}

The policy tool could be used as a Java library in a project using a \code{PolicyResolutor} object and a \code{PolicyReconciliator} object that could not be instantiated.

They offer two methods, "generateResolutedPolicy" method to generate a resoulted policy and "generateReconciliedPolicy" method to generate reconclilied policy to avoid misconfigurations in the security policies.

\begin{itemize}
	\item 
	{\ttfamily public static PolicyImpl generateResolutedPolicy(Policy originalPolicy, SelectorTypes selectorTypes)}
	
	it allows to create a new policy, starting from one, that has no rules anomalies or conflicts based on the \code{FMRResolutionStrategy}.
	
	\item 
	{\ttfamily public static PolicyImpl generateReconciliedPolicy(Policy isp, Policy e, String ispName, String entityName,
		SelectorTypes selectorTypes)}
	
	it allows to create a new policy, starting from two policies, the "isp policy" has an higher priority then the "e policy".
\end{itemize}

\begin{figure}
\HRule
\begin{lstlisting}[numbers=left,stepnumber=1, language = Java]
// creation of a new resoluted policy
PolicyImpl originalPolicy = new PolicyImpl();
PolicyImpl resolutedPolicy = generateResolutedPolicy(originalPolicy, selectorTypes);

// creation of a new reconciled policy
PolicyImpl ispPolicy = new PolicyImpl();
PolicyImpl entityPolicy = new PolicyImpl();
PolicyImpl reconciledPolicy = generateReconciliedPolicy(ispPolicy,
entityPolicy, ispName, entityName, selectorTypes);

\end{lstlisting}
\HRule
\end{figure}
