verigraph/README.md

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 | Let’s look at how to deploy **VeriGraph** on Apache Tomcat. If you’re
   5   only interested in creating gRPC API and ``neo4jmanager`` is already
   6   deployed, you can skip this section and go straight to the
   7   `documentation <https://gitlab.com/serena.spinoso/DP2.2017.SpecialProject2.gRPC/tree/master/src/main/java/it/polito/grpc>`__
   8 | (though you might find it useful if Tomcat is not yet installed!).
   9
  10 **Windows**
  11
  12 -  install ``jdk1.8.X_YY``
  13    `here <http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html>`__
  14 -  set ambient variable ``JAVA_HOME`` to where you installed the jdk
  15    (e.g. ``C:\Program Files\Java\jdk1.8.X_YY``)
  16 -  install Apache Tomcat 8
  17    `here <https://tomcat.apache.org/download-80.cgi>`__
  18 -  install a pre-compiled distribution of Z3 from
  19    `here <https://github.com/Z3Prover/bin/tree/master/releases>`__
  20    and save the ``[z3_root]/bin`` content under ``[verigraph]/service/build``
  21 -  create the ``mcnet.jar`` of the ``mcnet.*`` packages and put into the ``[verigraph]/service/build`` directory
  22 -  download the qjutils library
  23    `here <https://github.com/quanla/classreloading/tree/master/src/main/java/qj/util>`__
  24    and create a jar file (i.e. qjutils.jat) in ``[verigrap]/service/build``
  25 -  set ambient variable ``CATALINA_HOME`` to the directory where you
  26    installed Apache (e.g.
  27    ``C:\Program Files\Java\apache-tomcat-8.0.30``)
  28 -  create ``shared`` folder under ``%CATALINA_HOME%``
  29 -  add previously created folder to the Windows ``Path`` system variable
  30    (i.e. append the following string at the end:
  31    ``;%CATALINA_HOME%\shared``)
  32 -  copy ``[verigraph]/lib/mcnet.jar``, ``[verigraph]/service/build/com.microsoft.z3.jar`` and ``[verigraph]/service/build/qjutils.jar``
  33    to ``%CATALINA_HOME%\shared``
  34 -  to correctly compile the code you have to put the path of ``com.microsoft.z3.jar``
  35    and the libraries it refers to as environment variable. i.e. is enough
  36    to add the project subfolder ``build`` to the PATH environment variable (i.e., ``[verigraph]/build``)
  37 -  create custom file setenv.bat under ``%CATALINA_HOME%\bin`` with the
  38    following content:
  39
  40    .. code:: bat
  41
  42        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
  43
  44 -  download ``neo4jmanager.war`` from
  45    `here <https://github.com/netgroup-polito/verigraph/tree/master/dist>`__
  46    and copy into into ``%CATALINA_HOME%\webapps``
  47 -  export the ``verify.war`` file from the project and copy into ``%CATALINA_HOME%\webapps``
  48 -  (optional) configure Tomcat Manager:
  49 -  open the file ``%CATALINA_HOME%\conf\tomcat-users.xml``
  50 -  under the ``tomcat-users`` tag place the following content:
  51    ``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"/>``
  52 -  launch Tomcat 8 with the startup script
  53    ``%CATALINA_HOME%\bin\startup.bat``
  54 -  (optional) if you previously configured Tomcat Manager you can open a
  55    browser and navigate to `this link <http://localhost:8080/manager>`__
  56    and login using ``tomcat/tomcat`` as username/password
  57 -  (optional) you can deploy/undeploy/redeploy the downloaded WARs
  58    through the web interface
  59
  60 **Unix**
  61
  62 -  install ``jdk1.8.X_YY`` from the command line:
  63 -  go to `this
  64    link <http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html>`__
  65    to check the appropriate version for you OS and architecture
  66 -  copy the desired version to the clipboard (e.g.
  67    ``http://download.oracle.com/otn-pub/java/jdk/7u79-b15/jdk-7u79-linux-x64.tar.gz``)
  68 -  open a terminal windows and paste the following command (replace
  69    ``link`` with the previously copied link):
  70    ``wget --no-check-certificate --no-cookies --header "Cookie: oraclelicense=accept-securebackup-cookie" 'link'``
  71    e.g.
  72    ``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``
  73 -  untar the archive with the following command (replace 'jdk' to match
  74    the name of the downloaded archive):
  75    ``tar zxvf 'jdk'.tar.gz``
  76    e.g.
  77    ``tar zxvf jdk-7u<version>-linux-x64.tar.gz``
  78 -  delete the ``.tar.gz`` file if you want to save disk space
  79 -  install and configure Apache Tomcat 8 with the following commands:
  80 -  go to `this URL <http://it.apache.contactlab.it/tomcat/tomcat-8/>`__
  81    and see what the latest available version is
  82 -  download the archive (substitute every occurrence of '8.0.32' in the
  83    following command with the latest available version):
  84    ``wget http://it.apache.contactlab.it/tomcat/tomcat-8/v8.0.32/bin/apache-tomcat-8.0.32.tar.gz``
  85 -  extract downloaded archive:
  86    ``tar xvf apache-tomcat-8.0.32.tar.gz``
  87 -  edit configuration:
  88    ``nano ./apache-tomcat-8.0.32/conf/tomcat-users.xml``
  89 -  under the ``tomcat-users`` tag place the following content
  90    ``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>``
  91 -  set a few environment variables:
  92    ``sudo nano ~/.bashrc``
  93 -  paste the following content at the end of the file
  94    ``export CATALINA_HOME='/path/to/apache/tomcat/folder'``
  95    e.g.
  96    ``export CATALINA_HOME=/home/mininet/apache-tomcat-8.0.33``
  97    ``export JRE_HOME='/path/to/jdk/folder'``
  98    e.g.
  99    ``export JRE_HOME=/home/mininet/jdk1.8.0_92/jre``
 100    ``export JDK_HOME='/path/to/jdk/folder'``
 101    e.g.
 102    ``export JDK_HOME=/home/mininet/jdk1.8.0_92``
 103    ``export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CATALINA_HOME/shared``
 104    ``export JAVA_OPTS="-Djava.library.path=$CATALINA_HOME/shared"``
 105 -  ``exec bash``
 106 -  install a pre-compiled distribution of Z3 from
 107    `here <https://github.com/Z3Prover/bin/tree/master/releases>`__
 108    and save [z3_root]/bin content under ``[verigraph]/service/build``
 109 -  download the qjutils library
 110    `here <https://github.com/quanla/classreloading/tree/master/src/main/java/qj/util>`__
 111    and create a jar file (i.e. qjutils.jar) in ``[verigrap]/service/build``
 112 -  create the ``mcnet.jar`` of the ``mcnet.*`` packages and put into the ``[verigraph]/service/build`` directory
 113 -  copy ``[verigraph]/service/build/mcnet.jar``, ``[verigraph]/service/build/com.microsoft.z3.jar``
 114    and ``[verigraph]/service/build/qjutils.jar`` to ``$CATALINA_HOME/shared``
 115 -  customize Tomcat classpath
 116    ``nano $CATALINA_HOME/bin/setenv.sh``
 117 -  paste the following content and save file:
 118    ``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``
 119 -  save and close the file (``CTRL+O``, ``CTRL+X``)
 120    ``sudo chmod +x $CATALINA_HOME/bin/setenv.sh``
 121 -  download ``neo4jmanager.war`` from
 122    `here <https://github.com/netgroup-polito/verigraph/tree/master/dist>`__
 123    and copy into into ``%CATALINA_HOME%\webapps``
 124 -  export the ``verify.war`` file from the project and copy into ``%CATALINA_HOME%\webapps``
 125 -  launch Tomcat 8 with the startup script
 126    ``$CATALINA_HOME/bin/startup.sh``
 127 -  open a browser and navigate to `this
 128    link <http://localhost:8080/manager>`__ and login using
 129    ``tomcat/tomcat`` as username/password
 130 -  you can deploy/undeploy/redeploy the downloaded WARs through the web
 131    interface
 132
 133 **Eclipse**
 134
 135 -  clone project onto your hard drive with this command:
 136    ``git clone git@github.com:netgroup-polito/verigraph.git``
 137 -  Download Apache Tomcat 8 (see instructions above for Windows and
 138    Unix)
 139 -  Download JDK (see instructions above for Windows and Unix)
 140 -  Configure runtime environment in Eclipse with `the following
 141    incstructions <http://crunchify.com/step-by-step-guide-to-setup-and-install-apache-tomcat-server-in-eclipse-development-environment-ide/>`__
 142 -  Add new Tomcat server on port ``8080``
 143 -  Configure Tomcat server:
 144
 145    -  double-click on the newly created server in the ``Servers`` tab
 146    -  make sure under ``Server Locations`` ``Use Tomcat installation``
 147       is selected
 148    -  Open ``Launch Configuration``->``Classpath``
 149    -  add the required JARS (``mcnet.jar``, ``com.microsoft.z3.jar`` and
 150       ``qjutils.jar``) under ``User Entries``
 151    -  Hit ``Apply`` and ``Ok``
 152
 153 -  Run the server
 154
 155 **How to add you own function ``<type>``**
 156
 157 #. under the the ``mcnet.netobjs`` package (i.e. under
 158    ``/verify/service/src/mcnet/netobjs``) create a new class
 159    ``<Type>.java``, where ``<type>`` is the desired function name (i.e.
 160    ``<type>`` will be added to the supported node functional types)
 161    which extends ``NetworkObject`` and implement the desired logic
 162
 163 #. regenerate ``mcnet.jar`` selecting the packages ``mcnet.components``
 164    and ``mcnet.netobjs`` and exporting the generated JAR to
 165    ``/verify/service/build`` (overwrite the existing file)
 166
 167 #. under ``/verify/src/main/webapp/json/`` create a file
 168    ``<type>.json``. This file represents a JSON schema (see
 169    `here <http://json-schema.org/>`__ the official documentation). For
 170    compatibility with the other functions it is mandatory to support an
 171    array as the root of the configuration, but feel free to specify all
 172    the other constraints as needed. A sample of ``<type>.json`` to
 173    describe an empty configuration could be the following:
 174
 175 ``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   }``
 176
 177 #. in the package ``it.polito.escape.verify.validation`` (i.e. under
 178    ``src/main/java/it/polito/escape/verify/validation``) create a new
 179    class file named ``<Type>Validator.java`` (please pay attention to
 180    the naming convention here: ``<Type>`` is the function type used in
 181    the previous step capitalized, followed by the suffix ``Validator``)
 182    which implements ``ValidationInterface``. This class represents a
 183    custom validator for the newly introduced type and allows for more
 184    complex constraints, which is not possible to express through a JSON
 185    schema file. The validate method that has to be implemented is given
 186    the following objects:
 187
 188 -  ``Graph graph`` represents the nffg that the object node belongs to;
 189 -  ``Node node`` represents the node that the object configuration
 190    belongs to;
 191 -  ``Configuration configuration`` represents the parsed configuration.
 192    It is sufficient to call the method ``getConfiguration`` on the
 193    ``configuration`` object to get a ``JsonNode`` (Jackson's class) and
 194    iterate over the various fields.
 195    In case a configuration is not valid please throw a new
 196    ``ValidationException`` passing a descriptive failure message.
 197    Adding a custom validator is not strictly necessary whenever a JSON
 198    schema is thought to be sufficient. Note though that, other than the
 199    mandatory validation against a schema, whenever a custom validator is
 200    not found a default validation is triggered, i.e. the value of every
 201    JSON property must refer to the name of an existing node in the
 202    working graph/nffg. If this is not the desired behavior it is
 203    suggested to write a custom validator with looser constraints.
 204
 205 #. customize the class generator and add the support for the newly
 206    introduced type:
 207
 208 -  open the file
 209    ``/verify/service/src/tests/j-verigraph-generator/config.py`` and
 210    edit the following dictionaries:
 211
 212    -  ``devices_to_classes`` --> add the following entry:
 213       ``"<type>" : "<Type>"``
 214       if you followed these instructions carefully the name of the class
 215       implementing the function ``<type>`` should be ``<Type>.java``
 216       under the package ``mcnet.netobjs``.
 217    -  ``devices_to_configuration_methods`` --> add the following entry:
 218       ``"<type>" : "configurationMethod"``
 219       if ``<type>`` is a middlebox it should have a configuration method
 220       contained in the implementation ``<Type>.java`` under the package
 221       ``mcnet.netobjs``.
 222    -  ``devices_initialization``: add the following entry:
 223       ``"<type>" : ["param1", "param2"]``
 224       if ``<type>`` requires any parameter when it gets instanciated
 225       please enter them in the form of a list. Make sure that these
 226       parameters refer to existing keys contained in the configuration
 227       schema file (see step 3). For instance the type ``webclient``
 228       requires the name of a webserver it wants to communicate with.
 229       This parameter is passed in the configuration of a weblient by
 230       setting a property ``webserver`` to the name of the desired
 231       webserver. The value of this property gets extracted and used by
 232       the test generator automatically.
 233    -  ``convert_configuration_property_to_ip`` --> add the following
 234       entry: ``"<type>" : ["key", "value"]``
 235       Note that both ``key`` and ``value`` are optional and it is
 236       critical to set them only if needed. Since the Z3 provider used
 237       for testing works with IP addresses in this dictionary you have to
 238       indicate whether it is needed an automatic convertion from names
 239       to IP addresses:
 240    -  in case the keyword ``key`` is used every key of the JSON
 241       configuration parsed will be prepended with the string ``ip_``;
 242    -  in case the keyword ``value`` is used every value of the JSON
 243       configuration parsed will be prepended with the string ``ip_``;
 244    -  in case the list does not contain neither ``key`` nor ``value``
 245       the original configuration won't be touched.
 246
 247 -  open the file
 248    ``/verify/service/src/tests/j-verigraph-generator/test_class_generator.py``
 249    and under the "switch" case in the form of a series of ifs used to
 250    configure middle-boxes that starts at line #239 add a branch like the
 251    following with the logic to generate the Java code for -->
 252    ``elif nodes_types[i] == "<type>":``
 253    You can take inspiration from the other branches to see how to
 254    serialize Java code. Note that this addition to the "switch"
 255    statement is not needed if ``<type>`` is not a middlebox or it does
 256    not need to be configured.
 257
 258 #. Restart the web service.