MUSESDevGuide.tex

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Vertical Line Title Page 
% LaTeX Template
% Version 1.0 (27/12/12)
%
% This template has been downloaded from:
% http://www.LaTeXTemplates.com
%
% Original author:
% Peter Wilson (herries.press@earthlink.net)
%
% License:
% CC BY-NC-SA 3.0 (http://creativecommons.org/licenses/by-nc-sa/3.0/)
% 
% Instructions for using this template:
% This title page compiles as is. If you wish to include this title page in 
% another document, you will need to copy everything before 
% \begin{document} into the preamble of your document. The title page is
% then included using \titleGM within your document.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%----------------------------------------------------------------------------------------
%	PACKAGES AND OTHER DOCUMENT CONFIGURATIONS
%----------------------------------------------------------------------------------------

\documentclass[a4paper,11pt]{book}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{lmodern}
\usepackage{url}
\usepackage{graphicx}
\usepackage[UKenglish]{babel}
\usepackage[UKenglish]{isodate}
\usepackage{enumitem}

\newcommand*{\plogo}{\fbox{$\mathcal{PL}$}} % Generic publisher logo

%----------------------------------------------------------------------------------------
%	TITLE PAGE
%----------------------------------------------------------------------------------------

\newcommand*{\titleGM}{\begingroup % Create the command for including the title page in the document
\hbox{ % Horizontal box
\hspace*{0.2\textwidth} % Whitespace to the left of the title page
\rule{1pt}{\textheight} % Vertical line
\hspace*{0.05\textwidth} % Whitespace between the vertical line and title page text
\parbox[b]{0.75\textwidth}{ % Paragraph box which restricts text to less than the width of the page

{\noindent\Huge\bfseries \includegraphics[width=4cm]{./Figures/muses.png} \\[0.5\baselineskip] Developer Guide}\\[2\baselineskip] % Title
{\large \textit{Development \& Installation on a system}}\\[4\baselineskip] % Tagline or further description
{\Large \textsc{Sweden Connectivity AB, S2 Grupo, University of Granada, HiTec, \\University of Geneva}} % Author name

\vspace{0.3\textheight} % Whitespace between the title block and the publisher
{\includegraphics[width=1.5cm]{./Figures/EuropeanComission_en.png}\\
This project has received funding from the European Union's Seventh Framework Programme for research, technological development and demonstration under grant agreement No. 318508.}\\[\baselineskip] % Publisher and logo
}}
\endgroup}

%----------------------------------------------------------------------------------------
%	BLANK DOCUMENT
%----------------------------------------------------------------------------------------

\addto{\captionsspanish}{\renewcommand{\chaptername}{Chapter}}
\addto{\captionsspanish}{\renewcommand{\appendixname}{Appendix}}
\addto{\captionsspanish}{\renewcommand{\indexname}{Appendix}}
\addto{\captionsspanish}{\renewcommand{\contentsname}{Appendix}}
\addto{\captionsspanish}{\renewcommand{\bibname}{Bibliography}}

\cleanlookdateon

\begin{document}

\pagestyle{empty}

\titleGM % This command includes the title page
\tableofcontents

\chapter{Introduction}
\label{ch:intro}

This guide describes everything a developer needs to know to start developing for the MUSES system.

The MUSES System \cite{deliverable21} has been developed based on the client-server architecture. 
 
The client or device is related to the end user, usually an employee who uses a mobile or a portable device possibly
personal device to access enterprise resources. From the enterprise security point of view, the system should prevent the user from using the device incorrectly and make sure that the employee follows the company policies. Therefore, MUSES monitors the user's context and behaviour, and controls their actions, allowing or forbidding them depending on company policies.

The MUSES server is controlled by an enterprise security manager, the Chief Security Officer (CSO), who defines the security policies to be considered in the MUSES system. The security policies are used by the MUSES server to identify which behaviour is allowed and which one is not. The server then receives, stores, and processes all the gathered information from users' devices. After that, it analyzes the data, performing a real-time risk and trust analysis. In addition, the system detects policy violations through event correlation techniques, adapting to changes in the environment, as well as non-secure user behaviours.

\section{MUSES on Github}
\label{sec:musesgit}

All the MUSES system code is available at \url{https://github.com/MusesProject}. That is the Github organisation page for MUSES, and it contains the following repositories:

\begin{description}
  \item[Muses-Developer-Guide] Repository with the TeX files which consist of a manual for users that may want to develop for the MUSES project.
  \item[Muses-Security-Quiz] Contains the first version of the Spring roo project that implements the Security Quiz for MUSES project.
  \item[MusesCommon] This repository contains the Java classes which are common for client and server projects, to reduce duplication of classes in projects.
  \item[MusesServer] This repository contains all the files in the Java-Maven MUSES server project.
  \item[MusesClient] Repository containing the first prototype of the MUSES client, developed for Android.
  \item[MusesSituationPredictionStudy] Contains the very first
    prototype of an Android app that uses supervised learning to
    identify, whether the current device usage is private or
    professional, with on-device classification. 
  \item[MusesClientIOS] Repository containing the first prototype of the MUSES client, developed for iOS.
  \item[MusesAwareLibIOS] A library that can be used by applications to retrieve information relevant for MUSES.
  \item[MusesAwareApp] It contains the files of an Android project which consists of a MUSES-aware application. A MUSES-Aware application is an application that uses the MUSES API in order to notify MUSES of user interactions and adapt its behaviour based on MUSES provided commands/security decisions \cite{deliverable24}.
  \item[MusesAwareAppTest] Code for testing the MUSES-Aware
    application. % You should describe _what_ it is too. Test code? - JJ
\end{description}

This guide is structured as follows. First, Chapters \ref{ch:client} and \ref{ch:server} detail how to build MUSES, in order to be able to star developing and testing the system, either you want to develop for the client (Chapter \ref{ch:client}), the server (Chapter \ref{ch:server}), or both. Then, Chapter \ref{ch:sensors} specifies how to integrate new sensors to the MUSES client, for better monitoring user's actions and making the \textit{context\footnote{Any information that can be used to characterize the situation of the user.\cite{deliverable61}} observation} more complete. Finally, Chapter \ref{ch:installmuses} enumerates the steps to install MUSES in a real company environment.

\chapter{Building MUSES Client}
\label{ch:client}

The first prototype of MUSES has been developed for Android. This chapter describes the needed tools, as well as building instructions, for developing inside the MUSES client. For instructions about how to install the whole system, please refer to Chapter \ref{ch:installmuses}.

\begin{enumerate}
	\item Prepare eclipse (or any other IDE) for Android.
	\item Building the Common project.
	\item Deploy the app on a device or emulator (Building Client project).
	\begin{enumerate}[label*=\arabic*.]
		\item Create an emulator.
		\item Prepare your device for USB debugging.
		\item Deploy.
	\end{enumerate}
\end{enumerate}


\section{Installing Android SDK}
\label{sec:ADT}

As we will use Eclipse for MUSES development, the first step is to install the Android Development Tools (ADT) plugin. The requirements are \cite{adt:site}:

\begin{itemize}
  \item Eclipse 3.7.2 (Indigo) or greater.
  \item Java Platform (JDK) 6.
  \item Eclipse Java Development Tools (JDT) plugin. To install this plugin, in Eclipse go to \textit{Help > Install New Software...}, and make sure the \textit{Eclipse <youreclipsename> Update Site} is available by clicking in \textit{Find more software by working with the Available Software Sites preferences.}. Then select it and on the package list, look for \textit{Programming Languages > Eclipse Java Development Tools}. Finally, select Eclipse Java Development Tools and click \textit{Next} and \textit{Finish}. Eclipse will need to be restarted.
\end{itemize}

Now we can install the ADT plugin. This can be done by selecting again \textit{Help > Install New Software...} and then looking at this repository \url{https://dl-ssl.google.com/android/eclipse/}. After that, selecting \textit{Developer Tools} from the package list for installing it (by clicking \textit{Next} and \textit{Finish}), and then restart Eclipse one more time.

\section{Building Common project}
\label{sec:common}

In order to build the server project, we need to build the common project first as the server project has references to common project. As said in Section \ref{sec:musesgit}, \textit{MusesCommon} is located inside a repository of the MUSES organisation in GitHub (\url{https://github.com/MusesProject}). You can either download it as a ZIP file, or simply clone or fork the repository. For more information about Git, please refer to GitHub Help \cite{githelp:site}.

Please note that this is a Maven project (\url{http://maven.apache.org/}). For this reason, Eclipse should have Maven integrated. Following the steps for installing the JDK or ADK plugins, we should go to Eclipse\textit{Help > Install New Software...}. Maven will be at \url{http://download.eclipse.org/technology/m2e/releases} repository \cite{m2eclipse:site}.

Having this done, next step is to import the common project. On Eclipse, click on \textit{File > Import...}. A dialog will show up, to select the import source. A folder with the name ``Maven'' should appear, like in Figure \ref{fig:importdialog}. If not, please make sure that you have installed Maven for Eclipse, and successfully restarted Eclipse.

\begin{figure}
  \begin{center}
    \includegraphics[width=0.6\textwidth]{./Figures/importdialog.png}
    \caption{Shown dialog after clicking on \textit{File > Import...} inside Eclipse.}
    \label{fig:importdialog}
  \end{center}
\end{figure}

Click on \textit{Existing Maven Projects} and \textit{Next}. Then \textit{Browse...} the folder where the project is stored. Finally, click \textit{Next} and \textit{Finish}. For running projects with Maven, you must right-click on the project, and then go to \textit{Run As > Maven clean}, as it is shown in Figure \ref{fig:RunAs}. In the console, you will see a ``BUILD SUCCESS'', and then, repeat going to \textit{Run As > Maven install}. Now we are ready to import and run the client.

\begin{figure}
  \begin{center}
    \includegraphics[width=0.65\textwidth]{./Figures/runAs.png}
    \caption{How to run a Maven project by making \textit{Run As > Maven clean}, and then \textit{Run As > Maven install}.}
    \label{fig:RunAs}
  \end{center}
\end{figure}

\section{Building Client project}
\label{sec:buildclient}
This section is split into three parts \textit{1. Create an emulator}, \textit{2. Prepare your device for USB debugging}, and \textit{3. Deploy}, each of them describing the necessary steps.

\subsection{Create an emulator}
\label{sec:createanemulator}
This step is optional and should just be performed if you don't own an Android device to test with, because the emulator of Android has a bad performance and does not support the full functionality of a device, which can influence your debugging experience.
\\
\linebreak
In order to create an emulator, you have to open the Android Virtual Device Manager (ADV). In Figure \ref{fig:emu_part_1} you can see that you can open the ADV by following step 1, which shows the corresponding icon in the toolbar of eclipse. Alternatively, you can open this dialog in eclipse by following: \textit{Windows -> Android Virtual Device Manager}. Open the emulator creator (step 2 in Figure \ref{fig:emu_part_1}) and fill in the fields with your preferences. Remember, we use the target SDK level 19 in the MUSES project.

\begin{figure}
  \begin{center}
    \includegraphics[width=0.8\textwidth]{./Figures/emulator_part_1}
    \label{fig:emu_part_1}
    \caption{Open the emulator window}
  \end{center}
\end{figure}



\subsection{Prepare your device for USB debugging}
\label{sec:prepareyourdeviceforusbdebugging}
Android devices do not support debugging by default, you have to activate the debugging menu on the device manually. Go to the settings of your device and search for the \emph{Build Number}, the location on this setting depends on your device; then you need to click on the \emph{Build Number} seven times. After this, the developer menu is visible in the settings; open this menu and activate \emph{USB debugging}. If your operating system is Windows, you need to download the \emph{USB driver} from the Android SDK Manager (manual: \url{http://developer.android.com/sdk/win-usb.html}), if you are using a mac with OS X, you do not need to perform any further step. If you are using Linux you need to add a \emph{udev} rule (more information about i on \url{http://developer.android.com/tools/device.html#setting-up} step 3).
 
\subsection{Deployment}
\label{sec:deploytheclient}
The deployment process is straight forward, you just need to right click you project and select \emph{Run As -> Android Project}. Alternatively, you can also configure the deployment of the app and choose whether, you want to deploy the app on the emulator or the device by default, or if you would like to choose it individually for each deployment. Figure \ref{fig:run_config} shows the dialog of the configuration, you can open this dialog by right clicking on the project \emph{Run As -> Run configurations..}. 

\begin{figure}
  \begin{center}
    \includegraphics[width=0.8\textwidth]{./Figures/run_config}
    \label{fig:run_config}
    \caption{Optional run configuration}
  \end{center}
\end{figure}

\chapter{Building MUSES Server}
\label{ch:server}

MUSES server has been developed using open source guidelines. It implements an Apache Tomcat server, and a MySQL database. This chapter describes all necessary steps to follow in order to build the server and run tests in it.

\section{Necessary tools and configuration}
\label{sec:serverpreliminaries}

First of all, and as MUSES server has been developed with Eclipse, these are the required tools to be able to finally build the server project. Therefore, the following are needed:

\begin{itemize}
  \item Eclipse, no specific version.
  \item Package \textit{Eclipse IDE for Java EE Developers}. To do this, there are two choices:
  \begin{enumerate}
    \item In Eclipse go to \textit{Help > Install New Software...}, and select the \textit{http://download.eclipse.org/releases/<youreclipsename>} in the \textit{Work with:} drop-down. Then look for \textit{Web, XML, Java EE and OSGi Enterprise Development} on the package list, and select it. Click \textit{Next} and \textit{Finish}, and restart Eclipse.
    \item The package is available at \url{https://eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/lunasr2}, and the only thing to take into account is selecting the download according to your Eclipse version (name). On the website, simply select the correct one on ``Releases'', download it, and install it.
  \end{enumerate} 
  \item StartExplorer Eclipse plug-in. This plug-in is available at \url{http://basti1302.github.io/startexplorer/}, and you can just drag-and-drop the \textit{install} button on your Eclipse menu bar, or following the \textit{Help > Install New Software...} procedure.
\end{itemize}

Finally, as said in Section \ref{sec:musesgit}, \textit{MusesServer} files are located inside a repository of the MUSES organisation in GitHub (\url{https://github.com/MusesProject}). You can either download it as a ZIP file, or simply clone or fork the repository. For more information about Git, please refer to GitHub Help \cite{githelp:site}.

Before building the server project, MusesCommon project should be built. Please follow instructions of Section \ref{sec:common} before continue doing anything else.

\section{Building server project}
\label{sec:buildserver}

If Section \ref{sec:common} steps were successfully completed, we should have Maven correctly installed, and the MusesCommon project already built. Now, the MusesServer project should be imported into the workspace in the same way, as a Maven project.

As the database is implemented on MySQL, we have to make sure that we have the \textit{mysql-connector-java} library properly installed. By right-clicking on the server project, at the end of the emerging window click on \textit{Properties}. The library should appear in the list which is in \textit{Java Build Path > Libraries tab}. If it does not appear, click \textit{Cancel} and in Eclipse, go to \textit{Window > Show view > Other...}. In the new window, inside the \textit{Java} folder, select \textit{Package Explorer} and then \textit{OK}. A new tab will appear next to ``console'', ``error log'', ..., tabs. This tab shows the projects, like the \textit{Project Explorer} does. But in this view, we are able to use the \textit{StartExplorer} plug-in. By right-clicking in the MusesServer project, go to \textit{StartExplorer > Start Shell Here}, and a terminal will appear. If you cannot find this option, make sure that the \textit{StartExplorer} plug-in is installed (see Section \ref{sec:serverpreliminaries}). To obtain all the necessary configuration for managing MySQL databases and, in general, a Maven configuration for Eclipse, type into the terminal: \texttt{mvn eclipse:eclipse}. Wait for it to finish.

\subsection{Preparing the database}
\label{subsec:database}

The script for creating the MUSES server database is located at \texttt{MusesServer\\/db/startup\_db.sql}, and it should be loaded in the MySQL server at our machine. First, make sure you have MySQL server installed. If not, open a terminal and type \texttt{sudo apt-get install mysql-server-5.6}. During the installation, you will be asked to set a password for the root user. Few basic steps \cite{mysqlguide:site} should be followed to load the MUSES database:

\begin{description}
  \item[\texttt{\$ sudo /etc/init.d/mysql start}] 
  \item[\texttt{\$ mysql -u root -h localhost -p}] and then enter the chosen password.
  \item[\texttt{SOURCE /home/yourusername/foldertoMusesServer/db/startup\_db.sql;}] which loads the database structure from the script.
  \item[\texttt{SHOW DATABASES;}] should list the databases, and also MUSES database.
  \item[\texttt{USE muses;}]
  \item[\texttt{SOURCE /home/yourusername/foldertoMusesServer/db/startup\_db.sql;}] which populates the loaded database.
  \item[\texttt{SHOW TABLES;}] should list the tables inside MUSES database.
  \item[\texttt{CREATE USER 'muses'@'\%' IDENTIFIED BY 'muses11';}] creates a remote user for MUSES.
  \item[\texttt{GRANT ALL ON muses.* TO 'muses'@'\%';}] which gives permission to the MusesServer project to access the content in the MUSES database. Replace '\%' with localhost to make it only accessible from localhost.
\end{description}

Finally, go to Eclipse again, right-click on the MusesServer project, and then go to \textit{Run As > Maven clean}, as it was shown in Figure \ref{fig:RunAs}. In the console, you will see a ``BUILD SUCCESS'', and then, repeat going to \textit{Run As > Maven install}. Check that there were no errors, specially this type of error: \texttt{\textit{Error calling Driver\#connect}}, which means that the code cannot connect to the database. Now, you can implement functionalities and test them locally by doing \textit{Run As > Maven install} or \textit{Run As > Maven test}.

\section{Integrating Tomcat server}
\label{sec:eclipsetomcat}

Now that we can have a running client, by following the described steps on Section \ref{sec:buildclient}, and that we just built the server part (see previous section), it is time for integrating Tomcat on Eclipse. After that, we will be able to test our development in a client-server mode, and locally. And this is an important point, because this step is for development purposes only. To configure Apache Tomcat in a system, in order to work as a MUSES server, please refer to Section \ref{sec:tomcat}.

To integrate Apache Tomcat on Eclipse three steps are basically needed \cite{eclipsetomcat:site}: to install Apache Tomcat, to add it as a runtime environment, and to add the Tomcat server, strictly speaking.

\subsection{Installing Apache Tomcat}
\label{subsec:installapache}

Apache Tomcat powers numerous large-scale, mission-critical web applications across a diverse range of industries and organizations. But first of all, minimum Java Runtime Environment (JRE) 6 is required for Tomcat 7. For being able to install the last available version of JRE on the machine, open a terminal and follow this command:

\begin{verbatim}
$ sudo apt-get install openjdk-7-jre
\end{verbatim}

If you find problems with the dependencies, the command \texttt{\$ sudo apt-get -f install} fixes the possibly broken dependencies and finishes the installation. Also, you may need to update your system package list, for what you have to do the following:

\begin{description}
  \item[\$ sudo apt-get update] to update the lists.
  \item[\$ sudo apt-get upgrade] to install the new version of the packages, found by \textit{updating} the lists.
\end{description}

Find a correct Tomcat package to install by typing \texttt{\$ apt-cache search tomcat} and looking at the highlighted parts on Figure \ref{fig:tomcatpackages}. In this case, the needed version is version 7.

\begin{figure}
  \begin{center}
    \includegraphics[width=0.8\textwidth]{./Figures/tomcatpackages.png}
    \label{fig:tomcatpackages}
    \caption{What your terminal should show after introducing the \texttt{\$ apt-cache search tomcat} command. The highlighted packages are the ones we have to focus in.}
  \end{center}
\end{figure}

Then, to install the Tomcat server package, the following command is needed \cite{tomcatdocu:site}:

\begin{verbatim}
$ sudo apt-get install tomcat7
\end{verbatim}

And for now, what we need to know is that the configuration files will be at \texttt{/etc/tomcat7}, and the installation directory is \texttt{/usr/share/tomcat7}.

\subsection{Adding Apache Tomcat as a Runtime Environment}
\label{subsec:apacheSRE}

On Eclipse, go to \textit{Window > Preferences > Servers > Runtime environment > Add...} and after selecting \textit{Apache Tomcat v7.0}, and clicking \textit{Next}, we should see a window like the one shown in Figure \ref{fig:addingSRE}. As can be seen, we put the installation directory where is required and click \textit{Finish}. It should now appear on the window before we clicked \textit{Add...}. If not, check the steps before finally clicking \textit{OK}.

\begin{figure}
  \begin{center}
    \includegraphics[width=0.65\textwidth]{./Figures/addingSRE.png}
    \label{fig:addingSRE}
    \caption{Eclipse window which helps to add a new Runtime Environment. In our case, it will be Apache Tomcat version 7.}
  \end{center}
\end{figure}

\subsection{Adding Apache Tomcat as a server}
\label{subsec:addserver}

This is the last step. On Eclipse, right where the tabs of ``console'', ``error log'', ..., are, there is a tab called \textit{Servers}. A message like this should appear: ``No servers are available. Click this link to create a new server...''. Just click on this link or, if you have previously configured servers, just right-click and select \textit{New > Server}. We will see a list similar to the previous one, and we select again \textit{Apache Tomcat v7.0}. Finally, we write a name for our server and click \textit{Finish}. It should now appear in the list of servers at the Servers tab, as shown in Figure \ref{fig:createdtomcat}.

\begin{figure}
  \begin{center}
    \includegraphics[width=0.7\textwidth]{./Figures/createdtomcat.png}
    \label{fig:createdtomcat}
    \caption{Apache Tomcat installed and added into Eclipse.}
  \end{center}
\end{figure}

If all went well, and by making double-click on the server which was just added, a new window should appear, and it should look like Figure \ref{fig:serverconfig}. In this view, basic information about the Tomcat server on Eclipse can be changed.

\begin{figure}
  \begin{center}
    \includegraphics[width=0.85\textwidth]{./Figures/serverconfig.png}
    \label{fig:serverconfig}
    \caption{Editing basic information about the Apache Tomcat server.}
  \end{center}
\end{figure}

\chapter{Creating and integrating new sensors}
\label{ch:sensors}

A new sensor must implement the \texttt{eu.musesproject.client.contextmonitoring.\\sensors.ISensor} interface. This interface has six methods:

\begin{description}
  \item[void addContextListener(ContextListener listener);] This method takes a ContextListener object, the listener method \textbf{onEvent(ContextEvent contextEvent)} must be called whenever the sensor shall send an event to the MUSES system.
  \item[void removeContextListener(ContextListener listener);] Should contain a null object to remove the reference to the previous ContextListener object. Usually it is not necessary to call this method.
  \item[void enable();] The startup process of the sensor should be written or triggered in this method.
  \item[void disable();] Contains code to stop the sensor so that no more context events are fired to the system.
  \item[ContextEvent getLastFiredContextEvent();] Each sensor has a history of its fired context events; therefore a List<ContextEvents> must be implemented. The size of the list is limited by the static field CONTEXT\_EVENT\_HISTORY\_SIZE, which is located in the ISensor class. The developer has to take care to update the list probably.
  \item[void configure(List<SensorConfiguration> config);] If a sensor needs to be configured as it might expect specific values in order run as intended, the developer has to take care about the List<SensorConfiguration> config object. The SensorConfiguration class is located in the package: \texttt{eu.musesproject.client.db.entity}.
\end{description}

Each sensor must provide a \textbf{public static final String} \textit{TYPE} field. This field is used to identify the sensor. The naming convention is:\\\texttt{CONTEXT\_SENSOR\_<SensorIdentifier>}.
In addition, and in order to create properties for context events, the sensor must contain a \textbf{public static final String} field for each property identifier.

\section{How to integrate new sensors}
\label{sec:integratesensor}

First, new sensors should be placed within the MUSES Client project in the following package:
 
\begin{verbatim}
package eu.musesproject.client.contextmonitoring.sensors;
\end{verbatim}

Second, in the class:

\begin{verbatim}
eu.musesproject.client.contextmonitoring.SensorController
\end{verbatim}

the new sensor has to be initialized. And this has to be done inside the method: 

\begin{verbatim}
public void startAndConfigureSensors(List<String> enabledSensor){}
\end{verbatim}

Within this method the initialization has to be done as in the following example:

\begin{verbatim}
else if(sensorType.equals(SettingsSensor.TYPE)) {
sensor = new SettingsSensor(context); }
\end{verbatim}

\chapter{Installing MUSES}
\label{ch:installmuses}

Table \ref{tab:server_infrastructure} shows the hardware requirements to run MUSES server applications. The following sections will explain how to install and configure these requirements but the database, which was explained in Section \ref{subsec:database}.

\begin{table}[!htbp]
  \caption{MUSES server infrastructure.}
  \label{tab:server_infrastructure}

  \begin{center}
    \begin{tabular}{ |l|l|l| }
    \hline
    \multicolumn{3}{|c|}{\textbf{MUSES server}} \\
    \hline
    \textbf{Description} & \textbf{Name} & \textbf{Version} \\
    \hline
    Hardware & Desktop PC & Intel Core 64 bit \\
    OS & Ubuntu Desktop & 12.04 LTS \\
    Virtual Machine & JVM\footnote{Java Virtual Machine} & 1.6.0\_27 \\
    Servlet Container & Apache Tomcat & 7 \\
    WEB Server & Apache & 2.2.22 \\
    Database & MySQL & 5.5.31 \\
    \hline
    \end{tabular}
  \end{center}
\end{table}

\section{Configuring Apache Tomcat (Application Server)}
\label{sec:tomcat}

Section \ref{sec:eclipsetomcat} explained how to install the last version of Apache Tomcat server, because it was needed for developing purposes. Once you have followed the steps in that section, we continue configuring the server in order to finally have a working MUSES environment on our system.

As said in that section, Tomcat configuration files are at \texttt{/etc/tomcat7} directory. Among the configuration files, \textit{server.xml} can be found. Also, Figure \ref{fig:serverconfig} shown the configuration of Apache Tomcat, which includes the listening port. The default listening port for Apache is 8080, but we see in the figure that we have configured it at port 8888. The file \textit{server.xml} offers the possibility of changing the default port:
\\
\\
\begin{verbatim}
<Connector port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443" />
...
<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
\end{verbatim}

By simply changing \textit{connector port} 8080 for 8888. Please note that you may have to open \textit{server.xml} under superuser rights.

Then, we have to install the Tomcat web application administrator by this command \cite{tomcatdocu:site}:

\begin{verbatim}
$ sudo apt-get install tomcat7-admin
\end{verbatim}

In order to add manager privileges, and to be able to use Tomcat web applications like \textit{host-manager} \cite{tomcatdocu:site}, we need to define a \textit{``manager-gui''} user in \textit{tomcat-users.xml} file. This file is also among the configuration files at \texttt{/etc/tomcat7}. Open this file under superuser rights and make sure to change it until it looks like:

\begin{verbatim}
<?xml version='1.0' encoding='utf-8'?>
  <tomcat-users>
    <role rolename="manager-gui"/>
 	  <role rolename="manager"/>
 	  <role rolename="admin-gui"/>
    <role rolename="admin "/>
    <user username="admin" password="admin"
          roles="manager, manager-gui"/>
  </tomcat-users>
\end{verbatim}

\subsection{SSL configuration Tomcat}
\label{subsec:ssltomcat}

MUSES is using HTTPS in order to make the communication encrypted, and secure. SSL encryption has to be enabled in Tomcat server configuration with an SSL certificate location, on the server machine. Back again in the Tomcat configuration folder, at \texttt{/etc/tomcat7}, the \textit{web.xml} file allows to configure HTTPS on tomcat.

This way, open the \textit{web.xml} file and add the following lines:

\begin{verbatim}
<security-constraint>
  <web-resource-collection>
    <web-resource-name>ComMainServlet</web-resource-name>
    <url-pattern>/commain</url-pattern>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint>
\end{verbatim}

This will allow the MUSES servlet to listen for HTTPS connections. However, we also have to modify the file \textit{server.xml}, which is the same that have to be modified to change the listening port (see the beginning of this section). What we need now is to enable SSL authentication by adding:

\begin{verbatim}
<Connector
  SSLEnabled="true"
  ciphers="SSL_RSA_WITH_RC4_128_SHA"
  clientAuth="false"
  keystoreFile="/etc/tomcat7/keystore.jks"
  keystorePass="MUSES11"
  maxThreads="150"
  port="8443"
  protocol="HTTP/1.1"
  scheme="https" secure="true" sslProtocol="TLS" />
\end{verbatim}

Finally, Apache Tomcat has to be restarted in order to successfully apply the changes. This is done by:

\begin{verbatim}
$ sudo service tomcat restart
\end{verbatim}

\section{Starting MUSES}
\label{sec:musestart}

To be able to start MUSES, the WAR file (Web Archive file) is required. This war file can be found in the folder called release\_binaries inside the MusesServer project.
The Tomcat 7.0 application server setup requires deploying the war file in the tomcat container. Follow below instructions. 

Open a web browser and go to this link
\url{http://localhost:8080/manager/html} 
It will ask for the user name and password. Enter the credentials which have been set during tomcat configuration\footnote{In our case, we used admin/admin at \textit{tomcat-users.xml}, but they can be changed.}, then it will open the manager page for tomcat. Now in section \textit{\textbf{WAR file to deploy}} click on \textit{Browse...} and select the war file, then click \textit{Deploy}. 
After doing this, the application should be listed in the applications column. Now click on the application button to start the server.

\section{MUSES client}
\label{sec:musesclient}

The following steps can be followed either from Windows, MacOS, or Ubuntu.

First of all, in order to install the MUSES application on an Android phone, the MUSES APK file is needed. As said in Section \ref{sec:buildclient}, this is a file that results from compiling the client code. Then, for installing the APK, the MUSES APK file has to be stored into the SD card of the device. Finally, take the Android phone, click on the file once it is stored in the SD card and, wait for it to be installed.

Next step is to add the server certificate also to the SD card. This certificate has been named \textit{localhost.crt} and can be found at the MusesClient Github repository (for more details, please see Section \ref{sec:musesgit}), inside the \textit{Assets} folder. It is important to store this certificate at the device SD card root directory, so it should be at the location \textit{/sdcard/localhost.crt}.

Finally, we must add the configuration file. This file is named \textit{muses.conf} and can be found at base of the sdcard folder (/sdcard/muses.conf). Like the server certificate, the configuration file should be stored at the device SD card root directory.

\bibliographystyle{abbrv}
\bibliography{MUSESDevGuide}

\end{document}