IoTa-pub

Building and Installing

=======================

Building

--------

IoTa uses Apache Maven for build automation (http://maven.apache.org).

A convenience building script is provided: make-all.sh.

Compilation of each module is achieved with this command:

mvn compile

Maven will download all the necessary jar files and install them in a local

repository (usually ~/.m2/repository).

Installation of IoTa libraries in the local repository for further use (as

needed for several IoTa modules) is achieved with this command:

mvn install

Note that this command also compiles the module if necessary.

Some of the modules provide unit tests and some of these tests need some

application to be running (eg. the tests for the IoTa-DiscoveryWS-Client

library need an up and running Discovery Web Service). To skip those tests,

use this command to compile or install:

mvn -DskipTests install

You can manually install already downloaded jar files with this command:

mvn install:install-file \

-Dfile=sunxacml-2.0-SNAPSHOT.jar \

-DgroupId=net.sf.sunxacml \

-DartifactId=sunxacml \

-Dversion=2.0-SNAPSHOT \

-Dpackaging=jar

Note that this will be necessary for the sunxacml library as it’s on no

widespread known Maven repository. The jar file can be downloaded from the

SourceForge page for the project: http://sunxacml.sf.net

Here is a direct link: http://sourceforge.net/projects/sunxacml/files/maven/snapshots/net/sf/sunxacml/sunxacml/2.0-SNAPSHOT/sunxacml-2.0-SNAPSHOT.jar/download

Installing

----------

(All bracketted values `<name>` are place-holders.)

**The IoTa-Installer can help you to install and configure all the servers and

databases.**

All the applications and web applications have a `log4j.properties` file to

configure the logging output (file output, log format, log level, and so on).

### Applications

Get and extract the `<application>-<version>-bin-with-dependency.tar.gz`

tarball for the application.

Modify or create the configuration files (see the application `README` file

for a list and each file for comments).

A file in the current directory overrides the default version which is

embedded in the jar file.

You can extract the default commented version of the files from the jar file:

jar xf <application>-<version>.jar application.properties

or

unzip <application>-<version>.jar application.properties

Use the provided script to start the application.

### Servlet Container and SSL/TLS

A servlet container need to be installed.

For now, the IoTa-Installer knows only about Apache Tomcat (versions 6 or 7).

The IoTa-Installer can help you install and configure one.

In order to use SSL/TLS as a mutual authentication means for the IoTa web

applications and their clients, an SSL/TLS connector must be configured.

For Apache Tomcat 7, if you don’t use the IoTa-Installer, you need to add a

connector element similar to the following snippet in the file

`${CATALINA_HOME}/conf/server.xml`:

<Connector protocol="HTTP/1.1"

port="8443"

maxThreads="200"

scheme="https"

secure="true"

SSLEnabled="true"

keystoreFile="${catalina.home}/conf/ssl/keystore.jks"

keystorePass="changeit"

keyAlias="if_more_than_one_key_in_keystore"

keyPass="changeit"

truststoreFile="${catalina.home}/conf/ssl/truststore.jks"

truststorePass="changeit"

crlFile="${catalina.home}/conf/ssl/revocations_list.pem"

clientAuth="true"

sslProtocol="TLS"/>

Or, if the Apache Portable Runtime library (APR) is installed and used on the

target system:

<Connector protocol="HTTP/1.1"

port="8443"

maxThreads="200"

scheme="https"

secure="true"

SSLEnabled="true"

SSLCertificateFile="${catalina.home}/conf/ssl/server.crt"

SSLCertificateKeyFile="${catalina.home}/conf/ssl/server.pem"

SSLCACertificatePath="${catalina.home}/conf/ssl/clients/"

SSLCARevocationPath="${catalina.home}/conf/ssl/revocations/"

SSLVerifyClient="require"

SSLProtocol="TLSv1"/>

Add the client's certificates to the Tomcat's truststore, with a command like:

keytool -importcert -storetype "jks" -keystore "truststore.jks" -alias "key" -file "client.cert"

The ETa, OMeGa and EpcisPHi applications need roles in `$CATALINA_HOME/conf/tomcat-users.xml`

to manage identity with TLS:

* for ETa: <role rolename="eta_user"/>

* for OMeGa: <role rolename="omega_user"/>

* for EpcisPHi: <role rolename="ephi_user"/>

The names can be different depending on the configuration of

`<webapp-dir>/WEB-INF/web.xml`.

Each user who wants to request the services of ETa, OMeGa or the web interface

of EpcisPHi must be identified in `$CATALINA_HOME/conf/tomcat-users.xml`

and one or more roles must be attributed.

Each application using these services must be known.

The user (or application) is recognyzed by the Distinguished Name (DN) of

the certificate used to connect to the service.

The user roles (ETa and/or OMeGa and/or EpcisPHi) are determined by the

"roles" attribute and corresponds to the "rolename" above.

To add the ETa, OMeGa and EpcisPHi services to the user whose DN certificate is

"CN=foo", add to the `$CATALINA_HOME/conf/tomcat-users.xml` file:

<user username="CN=foo" password="" roles="eta_user,omega_user"/>

To log to the web interface of Epcis-PHi as "superadmin", who manages the user

accounts, you must use a certificate (generated by IoTa-Installer or keytool).

The DN of this certificate ("UID=superadmin" by default) needs to be similar to

the LDAP directory.

This user must be added to the previous file:

<user username="UID=superadmin" password="" roles="ephi_user"/>

### Web Applications

Get the `<application>-<version>.war` war file for the web application.

Deploy it in you servlet container (see the container documentation for

information). For Apache Tomcat, this can be done in several ways:

1. manually dejar the war file in `$CATALINA_HOME/webapps`

2. copy the war file in `$CATALINA_HOME/webapps` and let Tomcat deploy it

(either at its next restart or while running if its autodeploy option is

on)

3. use the manager web application (http://localhost:8080/manager)

4. use the deploy-tools

5. use the Maven Tomcat plugin

Edit the configuration files in `<webapp-dir>/WEB-INF/classes/` (see the web

application `README` for a list and each file for comments).

Reload the web application or restart the servlet container.

### Web Applications with databases

1. The database

Create the database for the application:

CREATE DATABASE <app_db>;

Create a specific user and grant them access rights:

GRANT SELECT, INSERT, UPDATE, DELETE ON <app_db>.*

TO <app_db_user>@localhost IDENTIFIED BY <app_db_password>;

Create the tables:

use <app_db>;

source <app>_schema.sql;

The file `<app>_schema.sql` for each application can be found in

`IoTa-Installer/resources` and in `<app>/src/main/resources/sql`.

2. Install the web application as explained earlier.

At this point, the web application will probably fail to properly start.

3. The context file

Modify the file `$CATALINA_HOME/webapps/<webapp>/META-INF/context.xml` to

reflect the values for your database (name, login and password).

Sometimes, it is needed to have a copy of this file as

`$CATALINA_HOME/conf/localhost/<webapp>.xml`.

Reload the web application or restart the servlet container.

Do not forget to install the JDBC connector jar file. (For Apache Tomcat and

MySQL, copy `mysql-connector-java.jar` in `$CATALINA_HOME/lib`.)

### ONS

Some applications need an Object Naming Service. NAPTR records are use to find

the URL of the Discovery Service for a given EPC code.

Here is a typical zone file for the product `urn:epc:id:sgtin:1234567.89012`:

;;

$TTL 1d

;; zone, the vendor Id

$ORIGIN 7.6.5.4.3.2.1.sgtin.id.ons-peer.com.

@ IN SOA localhost info.example.com ( ; info@example.com

2012010101 ; serial version number

3h ; refresh

1h ; retry

1d ; expire

1 ; negative cache TTL

)

;; this server’s name

IN NS ons.example.com.

; NAPTRs for products

; example product

; order pref flags service regex

2.1.0.9.8 IN NAPTR 0 0 "u" "epc+html" "!^.*$!http://www.example.com/!" .

IN NAPTR 1 0 "u" "epc+epcis" "!^.*$!http://epcis.example.com/epcis/!" .

IN NAPTR 2 0 "u" "epc+ided_epcis" "!^.*$!http://epcis.example.com/eta/!" .

IN NAPTR 3 0 "u" "epc+ds" "!^.*$!http://ds.example.com/ds/services/ESDS_Service!" .

IN NAPTR 4 0 "u" "epc+ds" "!^.*$!http://ds.example.com/dseta/ds/!" .

IN NAPTR 5 0 "u" "epc+ided_ds" "!^.*$!http://ds.example.com/dseta/ided_ds/!" .

; first, the HTML web page for product information

; then, the EPCIS-repository web service associated to this EPC

; then, the identified EPCIS-repository (ETa) web service associated to this EPC

; then, the Discovery web service associated to this EPC (WINGS version)

; then, the Discovery web service associated to this EPC

; finally, the identified Discovery web service associated to this EPC

; the order is free

On Debian and Debian-derived systems, you just need to install the `bind9`

package, to create one or more zone file as the cited example and to activate

those zones, that is to add that kind of statement in `named.conf.local`:

zone "7.6.5.4.3.2.1.sgtin.id.ons-peer.com" {

type master;

file "/etc/bind/db.ons.peer.com";

};

Remember that in order to avoid a recursive open relay DNS, you need to add

these options (in the `options` statement of `named.conf.options`):

allow-transfer { none; };

allow-recursion { none; };

recursion no;

### LDAP

Some applications (YPSilon) need an LDAP server.

From a fonctionnal LDAP server, the script `YPSilon/ldap.sh` or the LDAP module of

the IoTa-Installer adds a schema, a group and the two users superadmin and

anonymous.

On Debian and Debian-derived systems, you just need to install the packages

`slapd` and `ldap-utils`. You have to execute `dpkg-reconfigure slapd` in

order to complete the configuration.

To add index on attributes (like the DN of user certificate used when this DN is

incompatible with the LDAP tree, "aliasdn" by default), you can use the

ldapmodify command with this properties:

dn: olcDatabase={1}hdb,cn=config

changetype: modify

add: olcDbIndex

olcDbIndex: aliasdn eq

where "olcDatabase={1}hdb" is the used base.

### ActiveMQ

Some applications (ETa-Callback*) need an ActiveMQ JMS broker.

On Debian and Debian-derived systems, you just need to install the package

`activemq`.

### Memory Issues

Due to extensive introspection (e.g. by Hibernate or CXF), and if you want to

install all the web applications on the same server, the JVM “PermGen” memory

needs to be increased. For Apache Tomcat, it can be done with the environment

variable JAVA_OPTS. In POSIX shells, that can be done by a command like the

following one:

export JAVA_OPTS='-Xms2048m -Xmx4096m -XX:MaxPermSize=512m'

This environment variable needs to be set before starting Apache Tomcat hence

before starting the IoTa installer (as the IoTa installer starts Apache

Tomcat).

This is only necessary if you install all (or most of) the web applications in

the same servlet container.