diff options
Diffstat (limited to 'verigraph/README.md')
| -rw-r--r-- | verigraph/README.md | 258 |
1 files changed, 0 insertions, 258 deletions
diff --git a/verigraph/README.md b/verigraph/README.md deleted file mode 100644 index 947e893..0000000 --- a/verigraph/README.md +++ /dev/null @@ -1,258 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 - -| Let’s look at how to deploy **VeriGraph** on Apache Tomcat. If you’re - only interested in creating gRPC API and ``neo4jmanager`` is already - deployed, you can skip this section and go straight to the - `documentation <https://gitlab.com/serena.spinoso/DP2.2017.SpecialProject2.gRPC/tree/master/src/main/java/it/polito/grpc>`__ -| (though you might find it useful if Tomcat is not yet installed!). - -**Windows** - -- install ``jdk1.8.X_YY`` - `here <http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html>`__ -- set ambient variable ``JAVA_HOME`` to where you installed the jdk - (e.g. ``C:\Program Files\Java\jdk1.8.X_YY``) -- install Apache Tomcat 8 - `here <https://tomcat.apache.org/download-80.cgi>`__ -- install a pre-compiled distribution of Z3 from - `here <https://github.com/Z3Prover/bin/tree/master/releases>`__ - and save the ``[z3_root]/bin`` content under ``[verigraph]/service/build`` -- create the ``mcnet.jar`` of the ``mcnet.*`` packages and put into the ``[verigraph]/service/build`` directory -- download the qjutils library - `here <https://github.com/quanla/classreloading/tree/master/src/main/java/qj/util>`__ - and create a jar file (i.e. qjutils.jat) in ``[verigrap]/service/build`` -- set ambient variable ``CATALINA_HOME`` to the directory where you - installed Apache (e.g. - ``C:\Program Files\Java\apache-tomcat-8.0.30``) -- create ``shared`` folder under ``%CATALINA_HOME%`` -- add previously created folder to the Windows ``Path`` system variable - (i.e. append the following string at the end: - ``;%CATALINA_HOME%\shared``) -- copy ``[verigraph]/lib/mcnet.jar``, ``[verigraph]/service/build/com.microsoft.z3.jar`` and ``[verigraph]/service/build/qjutils.jar`` - to ``%CATALINA_HOME%\shared`` -- to correctly compile the code you have to put the path of ``com.microsoft.z3.jar`` - and the libraries it refers to as environment variable. i.e. is enough - to add the project subfolder ``build`` to the PATH environment variable (i.e., ``[verigraph]/build``) -- create custom file setenv.bat under ``%CATALINA_HOME%\bin`` with the - following content: - - .. code:: bat - - set CLASSPATH=%CLASSPATH%;%CATALINA_HOME%\shared\qjutils.jar;%CATALINA_HOME%\shared\mcnet.jar;%CATALINA_HOME%\shared\com.microsoft.z3.jar;.;%CATALINA_HOME%\webapps\verify\WEB-INF\classes\tests - -- download ``neo4jmanager.war`` from - `here <https://github.com/netgroup-polito/verigraph/tree/master/dist>`__ - and copy into into ``%CATALINA_HOME%\webapps`` -- export the ``verify.war`` file from the project and copy into ``%CATALINA_HOME%\webapps`` -- (optional) configure Tomcat Manager: -- open the file ``%CATALINA_HOME%\conf\tomcat-users.xml`` -- under the ``tomcat-users`` tag place the following content: - ``xml <role rolename="tomcat"/> <role rolename="role1"/> <user username="tomcat" password="tomcat" roles="tomcat,manager-gui"/> <user username="both" password="tomcat" roles="tomcat,role1"/> <user username="role1" password="tomcat" roles="role1"/>`` -- launch Tomcat 8 with the startup script - ``%CATALINA_HOME%\bin\startup.bat`` -- (optional) if you previously configured Tomcat Manager you can open a - browser and navigate to `this link <http://localhost:8080/manager>`__ - and login using ``tomcat/tomcat`` as username/password -- (optional) you can deploy/undeploy/redeploy the downloaded WARs - through the web interface - -**Unix** - -- install ``jdk1.8.X_YY`` from the command line: -- go to `this - link <http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html>`__ - to check the appropriate version for you OS and architecture -- copy the desired version to the clipboard (e.g. - ``http://download.oracle.com/otn-pub/java/jdk/7u79-b15/jdk-7u79-linux-x64.tar.gz``) -- open a terminal windows and paste the following command (replace - ``link`` with the previously copied link): - ``wget --no-check-certificate --no-cookies --header "Cookie: oraclelicense=accept-securebackup-cookie" 'link'`` - e.g. - ``wget --no-check-certificate --no-cookies --header "Cookie: oraclelicense=accept-securebackup-cookie" http://download.oracle.com/otn-pub/java/jdk/7u79-b15/jdk-7u79-linux-x64.tar.gz`` -- untar the archive with the following command (replace 'jdk' to match - the name of the downloaded archive): - ``tar zxvf 'jdk'.tar.gz`` - e.g. - ``tar zxvf jdk-7u<version>-linux-x64.tar.gz`` -- delete the ``.tar.gz`` file if you want to save disk space -- install and configure Apache Tomcat 8 with the following commands: -- go to `this URL <http://it.apache.contactlab.it/tomcat/tomcat-8/>`__ - and see what the latest available version is -- download the archive (substitute every occurrence of '8.0.32' in the - following command with the latest available version): - ``wget http://it.apache.contactlab.it/tomcat/tomcat-8/v8.0.32/bin/apache-tomcat-8.0.32.tar.gz`` -- extract downloaded archive: - ``tar xvf apache-tomcat-8.0.32.tar.gz`` -- edit configuration: - ``nano ./apache-tomcat-8.0.32/conf/tomcat-users.xml`` -- under the ``tomcat-users`` tag place the following content - ``xml <role rolename="tomcat"/> <role rolename="role1"/> <user username="tomcat" password="tomcat" roles="tomcat,manager-gui"/> <user username="both" password="tomcat" roles="tomcat,role1"/> <user username="role1" password="tomcat" roles="role1"/> </tomcat-users>`` -- set a few environment variables: - ``sudo nano ~/.bashrc`` -- paste the following content at the end of the file - ``export CATALINA_HOME='/path/to/apache/tomcat/folder'`` - e.g. - ``export CATALINA_HOME=/home/mininet/apache-tomcat-8.0.33`` - ``export JRE_HOME='/path/to/jdk/folder'`` - e.g. - ``export JRE_HOME=/home/mininet/jdk1.8.0_92/jre`` - ``export JDK_HOME='/path/to/jdk/folder'`` - e.g. - ``export JDK_HOME=/home/mininet/jdk1.8.0_92`` - ``export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CATALINA_HOME/shared`` - ``export JAVA_OPTS="-Djava.library.path=$CATALINA_HOME/shared"`` -- ``exec bash`` -- install a pre-compiled distribution of Z3 from - `here <https://github.com/Z3Prover/bin/tree/master/releases>`__ - and save [z3_root]/bin content under ``[verigraph]/service/build`` -- download the qjutils library - `here <https://github.com/quanla/classreloading/tree/master/src/main/java/qj/util>`__ - and create a jar file (i.e. qjutils.jar) in ``[verigrap]/service/build`` -- create the ``mcnet.jar`` of the ``mcnet.*`` packages and put into the ``[verigraph]/service/build`` directory -- copy ``[verigraph]/service/build/mcnet.jar``, ``[verigraph]/service/build/com.microsoft.z3.jar`` - and ``[verigraph]/service/build/qjutils.jar`` to ``$CATALINA_HOME/shared`` -- customize Tomcat classpath - ``nano $CATALINA_HOME/bin/setenv.sh`` -- paste the following content and save file: - ``bash #!/bin/sh export CLASSPATH=$CLASSPATH:$CATALINA_HOME/shared/qjutils.jar:$CATALINA_HOME/shared/mcnet.jar:$CATALINA_HOME/shared/com.microsoft.z3.jar:.:$CATALINA_HOME/webapps/verify/WEB-INF/classes/tests`` -- save and close the file (``CTRL+O``, ``CTRL+X``) - ``sudo chmod +x $CATALINA_HOME/bin/setenv.sh`` -- download ``neo4jmanager.war`` from - `here <https://github.com/netgroup-polito/verigraph/tree/master/dist>`__ - and copy into into ``%CATALINA_HOME%\webapps`` -- export the ``verify.war`` file from the project and copy into ``%CATALINA_HOME%\webapps`` -- launch Tomcat 8 with the startup script - ``$CATALINA_HOME/bin/startup.sh`` -- open a browser and navigate to `this - link <http://localhost:8080/manager>`__ and login using - ``tomcat/tomcat`` as username/password -- you can deploy/undeploy/redeploy the downloaded WARs through the web - interface - -**Eclipse** - -- clone project onto your hard drive with this command: - ``git clone git@github.com:netgroup-polito/verigraph.git`` -- Download Apache Tomcat 8 (see instructions above for Windows and - Unix) -- Download JDK (see instructions above for Windows and Unix) -- Configure runtime environment in Eclipse with `the following - incstructions <http://crunchify.com/step-by-step-guide-to-setup-and-install-apache-tomcat-server-in-eclipse-development-environment-ide/>`__ -- Add new Tomcat server on port ``8080`` -- Configure Tomcat server: - - - double-click on the newly created server in the ``Servers`` tab - - make sure under ``Server Locations`` ``Use Tomcat installation`` - is selected - - Open ``Launch Configuration``->``Classpath`` - - add the required JARS (``mcnet.jar``, ``com.microsoft.z3.jar`` and - ``qjutils.jar``) under ``User Entries`` - - Hit ``Apply`` and ``Ok`` - -- Run the server - -**How to add you own function ``<type>``** - -#. under the the ``mcnet.netobjs`` package (i.e. under - ``/verify/service/src/mcnet/netobjs``) create a new class - ``<Type>.java``, where ``<type>`` is the desired function name (i.e. - ``<type>`` will be added to the supported node functional types) - which extends ``NetworkObject`` and implement the desired logic - -#. regenerate ``mcnet.jar`` selecting the packages ``mcnet.components`` - and ``mcnet.netobjs`` and exporting the generated JAR to - ``/verify/service/build`` (overwrite the existing file) - -#. under ``/verify/src/main/webapp/json/`` create a file - ``<type>.json``. This file represents a JSON schema (see - `here <http://json-schema.org/>`__ the official documentation). For - compatibility with the other functions it is mandatory to support an - array as the root of the configuration, but feel free to specify all - the other constraints as needed. A sample of ``<type>.json`` to - describe an empty configuration could be the following: - -``json { "$schema": "http://json-schema.org/draft-04/schema#", "title": "Type", "description": "This is a generic type", "type": "array", "items": { "type": "object" }, "minItems": 0, "maxItems": 0, "uniqueItems": true }`` - -#. in the package ``it.polito.escape.verify.validation`` (i.e. under - ``src/main/java/it/polito/escape/verify/validation``) create a new - class file named ``<Type>Validator.java`` (please pay attention to - the naming convention here: ``<Type>`` is the function type used in - the previous step capitalized, followed by the suffix ``Validator``) - which implements ``ValidationInterface``. This class represents a - custom validator for the newly introduced type and allows for more - complex constraints, which is not possible to express through a JSON - schema file. The validate method that has to be implemented is given - the following objects: - -- ``Graph graph`` represents the nffg that the object node belongs to; -- ``Node node`` represents the node that the object configuration - belongs to; -- ``Configuration configuration`` represents the parsed configuration. - It is sufficient to call the method ``getConfiguration`` on the - ``configuration`` object to get a ``JsonNode`` (Jackson's class) and - iterate over the various fields. - In case a configuration is not valid please throw a new - ``ValidationException`` passing a descriptive failure message. - Adding a custom validator is not strictly necessary whenever a JSON - schema is thought to be sufficient. Note though that, other than the - mandatory validation against a schema, whenever a custom validator is - not found a default validation is triggered, i.e. the value of every - JSON property must refer to the name of an existing node in the - working graph/nffg. If this is not the desired behavior it is - suggested to write a custom validator with looser constraints. - -#. customize the class generator and add the support for the newly - introduced type: - -- open the file - ``/verify/service/src/tests/j-verigraph-generator/config.py`` and - edit the following dictionaries: - - - ``devices_to_classes`` --> add the following entry: - ``"<type>" : "<Type>"`` - if you followed these instructions carefully the name of the class - implementing the function ``<type>`` should be ``<Type>.java`` - under the package ``mcnet.netobjs``. - - ``devices_to_configuration_methods`` --> add the following entry: - ``"<type>" : "configurationMethod"`` - if ``<type>`` is a middlebox it should have a configuration method - contained in the implementation ``<Type>.java`` under the package - ``mcnet.netobjs``. - - ``devices_initialization``: add the following entry: - ``"<type>" : ["param1", "param2"]`` - if ``<type>`` requires any parameter when it gets instanciated - please enter them in the form of a list. Make sure that these - parameters refer to existing keys contained in the configuration - schema file (see step 3). For instance the type ``webclient`` - requires the name of a webserver it wants to communicate with. - This parameter is passed in the configuration of a weblient by - setting a property ``webserver`` to the name of the desired - webserver. The value of this property gets extracted and used by - the test generator automatically. - - ``convert_configuration_property_to_ip`` --> add the following - entry: ``"<type>" : ["key", "value"]`` - Note that both ``key`` and ``value`` are optional and it is - critical to set them only if needed. Since the Z3 provider used - for testing works with IP addresses in this dictionary you have to - indicate whether it is needed an automatic convertion from names - to IP addresses: - - in case the keyword ``key`` is used every key of the JSON - configuration parsed will be prepended with the string ``ip_``; - - in case the keyword ``value`` is used every value of the JSON - configuration parsed will be prepended with the string ``ip_``; - - in case the list does not contain neither ``key`` nor ``value`` - the original configuration won't be touched. - -- open the file - ``/verify/service/src/tests/j-verigraph-generator/test_class_generator.py`` - and under the "switch" case in the form of a series of ifs used to - configure middle-boxes that starts at line #239 add a branch like the - following with the logic to generate the Java code for --> - ``elif nodes_types[i] == "<type>":`` - You can take inspiration from the other branches to see how to - serialize Java code. Note that this addition to the "switch" - statement is not needed if ``<type>`` is not a middlebox or it does - not need to be configured. - -#. Restart the web service. |