| 180 | |
| 181 | [[PageOutline]] |
| 182 | |
| 183 | == Quickstart == |
| 184 | |
| 185 | From a service provider point of view the Sensei Framework consists of a few central services that can be distributed on different networked machines: Resource Directory (RD), Semantic Query Resolver (SQR), Entity Directory (ED), AAA Service (AAA), Privacy and Billling Service and the Execution Manager. |
| 186 | There are two ways to access these resources: there is a public access to the VM server farm in Bucharest with services linked to Ericsson, Telenor and Oulu University, or there is an all-in-one Virtual Machine used for development. |
| 187 | |
| 188 | The usual requirements for hosting these services are: |
| 189 | - a linux machine (we use RHEL-flavored operating systems, but any system should do) |
| 190 | - Sun Java JDK 6.0 |
| 191 | - Apache Tomcat v.6.0.20 |
| 192 | - Mysql 5 |
| 193 | - IPv6 |
| 194 | - SSL Certificates for AAA and Privacy & Billing |
| 195 | |
| 196 | IPv6 is needed for communicating with the nodes. For this, you can use a native IPv6 network or IPv6-over-IPv4 tunnels. The current Sensei network uses !GoGo6 (http://www.gogo6.com/) for Ipv6 tunneling. |
| 197 | |
| 198 | == Software requirements == |
| 199 | |
| 200 | |
| 201 | === Sun Java 6.0 JDK and Apache Ant === |
| 202 | |
| 203 | You can download the sdk from http://java.sun.com (direct link: http://www.oracle.com/technetwork/java/javase/downloads/index.html). Due to the fact that we'll be using java from the command line you should also set the necesarry environment variables JAVA_HOME and JDK_HOME. It is advisable to use the bin version of the archive and install it in /opt/java for example. |
| 204 | |
| 205 | Download java to /opt/java, make the file executable (chmod +x filename) and run it. In our example, java will be installed in ''/opt/java/jdk1.6.0_20''. Other locations possible to find the java instalation would be ''/usr/java'', ''/usr/lib/jvm'' (depending of the OS flavor). |
| 206 | |
| 207 | Put Java in the Environment Path by adding the following file to ''/etc/profile.d'': (filename ex: java.sh) |
| 208 | {{{ |
| 209 | export JAVA_HOME=/opt/java/jdk1.6.0_20 |
| 210 | export JDK_HOME=/opt/java/jdk1.6.0_20 |
| 211 | export ANT_HOME=/opt/apache-ant-1.8.1 |
| 212 | export PATH=/opt/java/jdk1.6.0_20/bin:/opt/apache-ant-1.8.1/bin:$PATH |
| 213 | }}} |
| 214 | |
| 215 | Several components might use compiling. If you do not have access to a GUI, then you can use Apache Ant (http://ant.apache.org/). Just download it and install it in ''/opt/apache-ant-1.8.1''. |
| 216 | |
| 217 | === Apache Tomcat & Mysql === |
| 218 | |
| 219 | You can use any application server you like. The one we used was Apache Tomcat 6.0.20. Just download it and unpack it in ''/opt/apache-tomcat-6.0.20''. For ease of development, we recommend using the tar.bz2 version for apache tomcat and the operating system provided mysql. |
| 220 | |
| 221 | To install mysql on a RHEL-flavored machine and configure it to run at startup: |
| 222 | {{{ |
| 223 | yum -y install mysql mysql-server |
| 224 | chkconfig mysqld on |
| 225 | }}} |
| 226 | |
| 227 | === IPv6 Connectivity === |
| 228 | |
| 229 | You may get IPv6 addresses from your ISP or you can tunnel IPv6 over an IPv4 network. |
| 230 | |
| 231 | If you want to use the setup for local development (nodes included) and do not need internet access through Ipv6, you can use '''radvd''', a linux IPv6 Router Daemon advertiser. For the address space, just go to http://www.simpledns.com/private-ipv6.aspx and get your own random private ipv6 address space. Theese networks will not get routed in the internet and you can use them locally. |
| 232 | |
| 233 | For Gogo6 you must go to http://www.gogo6.com/ and create yourself an account. (there is a the posbility of anonymous use also). You must download the FreeNet 6 client and run it. The client is named '''gw6c''' and we install it in ''/opt/gw6c''. The is a sample configuration file you must edit, gw6c.conf. The most important settings are: |
| 234 | |
| 235 | {{{ |
| 236 | # |
| 237 | userid= |
| 238 | passwd= |
| 239 | #server=anonymous.freenet6.net |
| 240 | server=authenticated.freenet6.net |
| 241 | # host_type=<host|router> |
| 242 | # |
| 243 | host_type=router |
| 244 | }}} |
| 245 | |
| 246 | To run it, run ''gw6c'' and it will daemonize by itself. To test your ipv6 setup just |
| 247 | {{{ |
| 248 | ping6 ipv6.google.com |
| 249 | }}} |
| 250 | |
| 251 | If you need a static address, just configure it from ''/etc/sysconfig/network'' |
| 252 | {{{ |
| 253 | NETWORKING=yes |
| 254 | NETWORKING_IPV6=yes |
| 255 | HOSTNAME=sensei-dev1.grid.pub.ro |
| 256 | }}} |
| 257 | |
| 258 | and ''/etc/sysconfig/network-scripts/ifcfg-eth0'' |
| 259 | {{{ |
| 260 | # Broadcom Corporation NetXtreme BCM5721 Gigabit Ethernet PCI Express |
| 261 | DEVICE=eth0 |
| 262 | BOOTPROTO=none |
| 263 | HWADDR=00:14:5E:30:9A:40 |
| 264 | IPADDR=141.85.224.33 |
| 265 | NETMASK=255.255.255.0 |
| 266 | NETWORK=141.85.224.0 |
| 267 | ONBOOT=yes |
| 268 | GATEWAY=141.85.224.1 |
| 269 | TYPE=Ethernet |
| 270 | IPV6INIT=yes |
| 271 | #IPV6ADDR=2607:f0d0:1002:0011:0000:0000:0000:0001 |
| 272 | #IPV6_DEFAULTGW=2607:f0d0:1002:0011:0000:0000:0000:0001 |
| 273 | }}} |
| 274 | |
| 275 | === SSL Certificates === |
| 276 | |
| 277 | This is the most important step for security services. Not only you got to have an ssl certificate, it must be '''trusted''' by all partners. You can get free SSL certificates at StartSSL for free, but for development you might consider to generate on youself. We will not cover this section here, you can use for example the CA.pl perl script in the openssl-perl package to create yourself a Cerificate Authority that will sign you cert, or you can use openssl directly. |
| 278 | |
| 279 | The important step is to tell tomcat an java about the certificates. |
| 280 | |
| 281 | To configure Tomcat you must follow these steps: http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html |
| 282 | The tricky bit is getting Java JRE to trust this certificate. The easyest way is to use this Java program. |
| 283 | |
| 284 | [to add link and howto] |
| 285 | |
| 286 | == Compiling Sensei Services using a CLI (Command Line Interface) == |
| 287 | |
| 288 | In case you need to compile the services you can use ant. Each project has a *.properties file for customizations. |
| 289 | To build a service: |
| 290 | {{{ |
| 291 | ant build |
| 292 | }}} |
| 293 | |
| 294 | To run a service. Just check the build target and run it: |
| 295 | {{{ |
| 296 | [root@sensei-dev1 SQRv2]# ant -p |
| 297 | Buildfile: build.xml |
| 298 | |
| 299 | Sensei SQRv2 |
| 300 | |
| 301 | Main targets: |
| 302 | |
| 303 | TestSQRLookup Run ARD Server |
| 304 | all Clean build and dist, then compile |
| 305 | build Build everything |
| 306 | clean Delete old build and dist directories |
| 307 | dist Dependency jar |
| 308 | runSQRv2Server Run ARD Server |
| 309 | Default target: build |
| 310 | [root@sensei-dev1 SQRv2]# ant runSQRv2Server |
| 311 | }}} |
| 312 | |
| 313 | In case you need as a daemon (close the terminal session and still have the service running, just use nohup. |
| 314 | {{{ |
| 315 | [root@sensei-dev1 SQRv2]# nohup ant runSQRv2Server & |
| 316 | }}} |
| 317 | |
| 318 | This will create a nohup.out file with all the output. |
| 319 | |
| 320 | == Running Sensei Services in the CLI == |
| 321 | |
| 322 | For running a service, you can use ant and nohup (in case you have source code access), or java directly |
| 323 | |
| 324 | {{{ |
| 325 | nohup java -jar RestEoiv3.jar & |
| 326 | }}} |
| 327 | |
| 328 | To check the service is running, look at the output file and/or check that the serivice is running on the specified port. |
| 329 | {{{ |
| 330 | [root@sensei-dev1 RESTEoiRepov3]# netstat -anp | grep java | grep LISTEN |
| 331 | tcp 0 0 :::9000 :::* LISTEN 2669/java |
| 332 | tcp 0 0 :::42896 :::* LISTEN 2669/java |
| 333 | }}} |
| 334 | |
| 335 | We have two services running on ports 9000 and 42896. |