IoTa-pub

Construction et installation

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

Construction

------------

IoTa utilise Apache Maven pour l’automatisation de la production

(http://maven.apache.org).

mvn compile

Maven téléchargera tous les fichiers jar nécessaires et les installera dans un

dépôt local (habituellement ~/.m2/repository).

L’installation des bibliothèques IoTa dans le dépôt local pour une utilisation

future (comme cela est nécessaire pour plusieurs modules IoTa) est réalisée

par la commande suivante :

mvn install

Notez que cette commande compile aussi le module si nécessaire.

Certains modules sont fournis avec des tests unitaires et certains de ces

tests nécessitent que des applications soient fonctionnelles (p.ex. les tests

de la bibliothèque IoTa-DiscoveryWS-Client veulent accéder à un serveur

IoTa-DiscoveryWS). Pour sauter ces tests, utilisez cette commande pour la

compilation ou l’installation :

mvn -DskipTests install

Vous pouvez installer manuellement des fichiers jar préalablement téléchargés

avec une commande de ce type :

mvn install:install-file \

-Dfile=sunxacml-2.0-SNAPSHOT.jar \

-DgroupId=net.sf.sunxacml \

-DartifactId=sunxacml \

-Dversion=2.0-SNAPSHOT \

-Dpackaging=jar

Notez que cela sera nécessaire pour la bibliothèque sunxacml puisque celle-ci

ne se trouve sur aucun dépôt Maven connu. Le fichier jar peut être téléchargé

depuis la page SourceForge du projet : http://sunxacml.sf.net.

Voici un lien direct : http://sourceforge.net/projects/sunxacml/files/maven/snapshots/net/sf/sunxacml/sunxacml/2.0-SNAPSHOT/sunxacml-2.0-SNAPSHOT.jar/download

Installation

------------

(Toutes les valeurs entre chevrons `<nom>` sont à substituer.)

les serveurs et bases de données.**

Toutes les applications et applications webs ont un fichier `log4j.properties`

pour configurer les journaux (fichier, format, niveau de log, etc.).

### Applications

Récupérez et extrayez le tarball de l’application

`<application>-<version>-bin-with-dependency.tar.gz`.

Modifiez ou créez les fichiers de configuration (voir le fichier `LISEZMOI` de

l’application pour une liste de ces fichiers et chaque fichier pour des

commentaires).

Un fichier dans le répertoire courant remplace la version par défaut qui est

intégrée au fichier jar.

Vous pouvez extraire la version par défaut commentée de ces fichiers depuis le

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

ou

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

Un conteneur de servlets doit être installé.

Pour le moment, le IoTa-Installer ne sait gérer qu’Apache Tomcat (versions 6

ou 7). Le IoTa-Installer peut vous aider à en installer un et à le configurer.

Pour utiliser SSL/TLS comme moyen d’authentification mutuelle entre les

applications web de IoTa et leurs clients, un `connector` SSL/TLS doit être

configuré.

Pour Apache Tomcat 7, si vous n’utilisez pas le IoTa-Installer, vous devez

ajouter un élément `connector` similaire à l’exemple suivant dans le fichier

`${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="si_plus_d’une_clef_dans_le_keystore"

keyPass="changeit"

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

truststorePass="changeit"

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

clientAuth="true"

sslProtocol="TLS"/>

Ou, si la bibliothèque Apache Portable Runtime (APR) est installée sur et

utilisée par le système cible :

<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"/>

Ajouter les certificats des clients à la liste des certificats de confiance

(truststore) de Tomcat, avec une commande du type:

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

Les applications OMeGa, ETa et EpcisPHi, pour gérer les identités en TLS, requièrent d'ajouter

au fichier `$CATALINA_HOME/conf/tomcat-users.xml` des rôles:

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

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

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

Les noms peuvent être différents selon la configuration des applications dans

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

Chaque utilisateur souhaitant interroger les services d'ETa, d'OMeGa ou

l'interface web d'EpcisPHi doit être identifié dans

`$CATALINA_HOME/conf/tomcat-users.xml` et un ou plusieurs rôles doivent

lui être attribués.

De même, chaque application utilisant ces services doit être connue.

L'utilisateur (ou application) est reconnu par le Distinguished Name (DN)

du certificat utilisé pour se connecter au service. Les rôles de l'utilisateur

(ETa et/ou OMeGa et/ou EpcisPHi) sont déterminés par l'attribut "roles" et

correspondent aux "rolename" ci-dessus.

Pour que l'utilisateur dont le DN du certificat est "CN=toto" puissent

utiliser les services d'ETA, d'OMeGa et d'EpcisPHi ajoutez au fichier

`$CATALINA_HOME/conf/tomcat-users.xml`:

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

Pour se connecter à l'interface web d'Epcis-PHi en tant que "superadmin",

qui gère les comptes utilisateurs, il est nécessaire d'utiliser un certificat

(généré via IoTa-Installer ou keytool) dont le DN (par défaut "UID=superadmin")

correspond à celui qui identifie "superadmin" dans l'annuaire LDAP.

Cet utilisateur doit être ajouté au fichier précédent:

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

Récupérez le fichier war de l’application web `<application>-<version>.war`.

Déployez-le dans votre conteneur de servlets (voir la documentation du

conteneur pour plus d’information). Pour Apache Tomcat, cela peut être fait de

1. déjarez manuellement le fichier war dans `$CATALINA_HOME/webapps`

2. copiez le fichier war dans `$CATALINA_HOME/webapps` et laissez Tomcat le

déployer (soit à son propchain redémarrage, soit à chaud si son option

autodeploy est active)

3. utilisez l’application web de gestion (http://localhost:8080/manager)

4. utilisez les outils de déploiement deploy-tools

5. utilisez le greffon Tomcat de Maven

Éditez les fichiers de configuration dans `<webapp-dir>/WEB-INF/classes/`

(voir le `LISEZMOI` de l’application web pour une liste de ces fichiers et

chaque fichier pour les commentaires).

Rechargez l’application web ou relancez le conteneur de servlet.

### Applications Web avec bases de données

1. La base de données

CREATE DATABASE <app_db>;

Créez un utilisateur spécifique et accordez-lui les droits d’accès à la

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

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

use <app_db>;

source <app>_schema.sql;

Le fichier `<app>_schema.sql` de chaque application se trouve dans

`IoTa-Installer/resources` et dans `<app>/src/main/resources/sql`.

2. Installez l’application web comme expliqué plus haut.

À ce point, l’application web n’arrivera probablement pas à démarrer

correctement.

3. Le fichier context

Modifiez le fichier `$CATALINA_HOME/webapps/<webapp>/META-INF/context.xml`

pour qu’il corresponde aux valeurs pour votre base de données (nom, login

et mot de passe).

Parfois, il est nécessaire d’avoir une copie de ce fichier en

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

Rechargez l’application web ou relancez le conteneur de servlet.

N’oubliez pas d’installer le fichier jar du connecteur JDBC. (Pour Apache

Tomcat et MySQL, copiez `mysql-connector-java.jar` dans `$CATALINA_HOME/lib`.)

### ONS

Certaines applications on besoin d’un service de nommage d’objet (ONS, Object

Naming Service). Des enregistrements NAPTR sont utilisés pour trouver l’URL du

service de découverte (Discovery Service) pour un code EPC donnée.

Voici un fichier de zone typique pour le produit

`urn:epc:id:sgtin:1234567.89012` :

;;

$TTL 1d

;; la zone, l’Id du fabricant

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

2012010101 ; numéro de version du fichier

3h ; rafraîchissement

1h ; réessai

1d ; expiration

1 ; TTL cache négatif

)

;; le nom de ce serveur

; NAPTR pour les produits

; produit exemple

; order pref flags service regex

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

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/!" .

; ensuite, le web service EPCIS-repository identifié (ETa) associé à cet EPC

; ensuite, le web service Discovery (Wings) associé à cet EPC

; ensuite, le web service Discovery associé à cet EPC

; finallement, le web service Discovery identifié associé à cet EPC

; l’ordre est libre

Sur les systèmes utilisant une distribution Debian ou dérivée, il suffit

d’installer le paquet `bind9`, de créer un ou plusieurs fichiers de zone sur

le modèle précédent et d’activer ces zones, c’est-à-dire d’ajouter ce genre de

clause dans `named.conf.local` :

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

};

Rappelons que pour éviter d’avoir un serveur relais récursif, il faut ajouter

ces options (dans la clause `options` de `named.conf.options`) :

allow-recursion { none; };

### LDAP

utilisateurs superadmin et anonymous.

Sur les distributions Debian et dérivées, il suffit d’installer les paquets

`slapd` et `ldap-utils`. Il est nécessaire de lancer `dpkg-reconfigure slapd`

pour compléter la configuration.

utilisateur utilisé quand ce DN n'est pas compatible avec l'arbre LDAP,

"aliasdn" par défaut), vous pouvez utiliser la commande ldapmodify avec les

propriétés suivantes:

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

changetype: modify

add: olcDbIndex

olcDbIndex: aliasdn eq

où olcDatabase={1}hdb correspond à la base utilisée.

### ActiveMQ

Certaines applications (ETa-Callback*) ont besoin d’un courtir JMS ActiveMQ.

Sur les distributions Debian et dérivées, il suffit d’installer le paquet

`activemq`.

### Problèmes de mémoire

Du fait d’un usage intensif de l’introspection (p.ex. par Hibernate et CXF),

et si vous voulez installer toutes les applications web sur le même serveur,

la mémoire « PermGen » de la JVM doit être augmentée. Pour Apache Tomcat, cela

peut être fait via la variable d’environnement JAVA_OPTS. Dans les shells

POSIX, il suffit d’une ligne de commande similaire à celle-ci:

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

Cette variable d’environnement doit être positionnée avant le lancement de

Apache Tomcat, donc avant le lancement de l’installateur IoTa (celui-ci

lançant Apache Tomcat)

Ceci n’est nécessaire que si vous installez toutes (ou presque toutes) les

applications web dans un même conteneur de servlet.