Mise à jour de juillet 2010 pour le routeur version 0.8.
Ce document spécifie un format de fichier .xpi2p (comme le .xpi de Firefox), mais avec un simple fichier de description plugin.config au lieu du fichier XML install.rdf. Ce fichier est utilisé pour l'installation initiale et pour les mises à jour.
De plus, ce document présente un aperçu résumé de l'installation des greffons par le routeur, et les stratégies et les grandes lignes de travail pour les développeurs.
Le format de base du fichier .xpi2p est le même que celui du fichier i2pupdate.sud (utilisé pour les mises à jour du routeur), mais le programme d'installation laisse faire l'utilisateur même si la clé de signature n'est pas encore connue.
La structure standard des répertoires permet l'installation des types de greffons suivants :
Un greffon installe tous ses fichiers dans ~/.i2p/plugins/nom/ (%APPDIR%\I2P\plugins\nom\ sur Windows). Le programme d'installation empêche l'installation ailleurs, bien que le greffon puisse accéder pour son fonctionnement à des bibliothèques situées en dehors de cette arborescence.
Ceci doit seulement être considéré comme un moyen pour faciliter l'installation, la désinstallation, et les mises à jour, ainsi que pour minimiser les conflits entre greffons.
Cependant, il n'y a pas de modèle de sécurité imposé lorsque le greffon est en cours d'exécution. Les greffons tournent dans la même JVM et avec les même privilèges que le routeur : ils ont l'accès total au système de fichiers, au routeur, à l'exécution de programmes etc…
foo.xpi2p est un fichier sud contenant les données suivantes :
En-tête standard .sud au début du fichier zip, contenant :
La signature DSA à 40 octets
La version du greffon sur 16 octets en UTF-8, complétée par des zéros en fin si nécessaire
Le fichier Zip contenant :
(REQUIS) un fichier plugin.config :
(fichier standard de configuration I2P, en UTF-8, contenant des lignes clé=valeur, les commentaires commençant par #)
Contenant les propriétés suivantes :
(* = requis)
Les trois premières doivent être identiques à celles du greffon installé s'il s'agit d'une mise à jour.
*name (le greffon sera installé dans ce dossier)
Pour les greffons spécifiques à un SE donné, vous pouvez séparer les noms pour des paquets différents, par exemple truc-windows et truc-linux.
*key (clé publique DSA sous forme Base64 de 172 caractères finissant '=')
*signer (votrenom@mail.i2p recommendé)
*version (dans un format compatible avec VersionComparator, p.e. 1.2.3-4)
16 octets maximum (doit correspondre à la version du sud)
Les séparateurs acceptés sont '.', '-', et '_'
Pour une mise à jour de greffon, doit être supérieure à celle actuellement installée.
configclients.jsp affichera les éléments suivants s'ils sont présents :
date (temps Java - entier long)
author (votrenom@mail.i2p recommendé)
websiteURL (http://truc.i2p/)
updateURL (http://truc.i2p/truc.xpi2p)
Le vérificateur de mises à jour contrôle les octets 41 à 56 à cette URL pour déterminer si une nouvelle version est disponible
(Le vérificateur va-t-il télécharger avec ?currentVersion=1.2.3?… Non. Si le développeur que l'URL contienne la version actuelle, il doit le préciser dans le fichier de configuration, et penser à le modifier à chaque nouvelle version)
description
description_xx (pour la langue xx)
license
disableStop=true
Par défault, false.
À true, le bouton "Arrêt" n'est pas affiché. À utiliser s'il n'y pas de client ni de
webapp avec des arguments d'arrêt.
Les éléments suivants servent à l'affichage d'un lien dans le panneau de contrôle de la console:
consoleLinkName (nom affiché dans le panneau de contrôle)
consoleLinkName_xx (pour la langue xx)
consoleLinkURL (/appname/index.jsp)
consoleLinkTooltip (supporté depuis la version 0.7.12-6)
consoleLinkTooltip_xx (idem, pour la langue xx)
Les éléments suivants concernent l'installeur du greffon :
type (app/theme/locale/webapp/...) (non implémenté, probablement inutile)
min-i2p-version
max-i2p-version
min-java-version
min-jetty-version
max-jetty-version
required-platform-OS (non implémenté - sera peut-être seulement affiché, pas vérifié)
other-requirements (non implémenté p.e. python x.y - non vérifié par l'installeur, uniquement
affiché)
dont-start-at-install=true
false par défaut.
router-restart-required=true
false par défaut.
dont-start-at-install doit être positionné à true pour être actif.
Ceci ne redémarre pas le routeur, indique seulement la nécessité de redémarrer.
update-only=true
false par défaut.
À true, un échec se produira si le greffon n'est pas déjà installé.
install-only=true
false par défaut.
À true, si le greffon est déjà installé, l'installation échouera.
min-installed-version (version minimale requise pour la mise à jour)
max-installed-version (version maximale requise pour la mise à jour)
depends=plugin1,plugin2,plugin3 (non implémenté - trop difficile? proposé par sponge)
depends-version=0.3.4,,5.6.7 (non implémenté)
Les éléments suivants sont pour les greffons de traduction :
langs=xx,yy,Klingon,... (non implémenté) (yy est le drapeau du pays)
Tous les dossiers et fichiers suivants sont optionnels , mais il faut mettre quelque-chose, ou il ne se
passera rien :
console/
locale/
Seulement des jars contenant de nouvelles ressources (traductions) pour les
applications de l'install de base I2P.
Les paquets de ce greffon vont dans console/webapp/truc.war ou lib/truc.jar
themes/
Nouveaux thèmes pour la console
Copier chaque thème dans un sous dossier.
webapps/
(voir plus bas les remarques importantes sur les applications web)
.wars
Ils seront lancés à l'installation sauf si désactivés dans webapps.config
Le nom du .war ne doit pas nécessairement être le même que celui du greffon.
Ne pas utiliser plusieurs fois le même nom de .war dans l'installation de base.
webapps.config
Même format que le webapps.config du routeur
Sert aussi à indiquer des .jars supplémentaires dans $PLUGIN/lib/ ou $I2P/lib pour le
classpath de la webapp, avec
webapps.warname.classpath=$PLUGIN/lib/foo.jar,$I2P/lib/bar.jar
NOTE : actuellement, la ligne classpath n'est chargée que si le nom du war est le même
que celui du greffon.
NOTE : avant sa version 0.7.12-9, le routeur cherchait plugin.warname.startOnLoad au
lieu de webapps.warname.startOnLoad. Pour la compatibilité avec les versions
antérieures, si un greffon doit désactiver un war, il doit comporter les deux lignes.
eepsite/
(Voir plus bas les remarques importantes sur les eepsites)
cgi-bin/
docroot/
logs/
webapps/
jetty.xml
L'installeur devra y substituer la variable pour définir le chemin
L'emplacement et le nom de ce fichier ne sont pas vraiment importants, tant qu'ils sont
définis dans clients.config - il peut être plus pratique d'être un niveau au dessus
dans l'arborescence (comme le fait le greffon zzzot)
lib/
Pour tous les jars. Les indiquer dans une ligne classpath de console/webapps.config et/ou clients.config
clients.config (même format que le clients.config du routeur)
Éléments lancés quand un greffon est démarré
Commence à client #0, en numérotation consécutive
New property clientApp.0.stopargs=truc machin stop bidule
Si présente, la classe sera appelée avec ces arguments pour arrêter le client
Toutes les tâches d'arrêt sont appelées avec un délais nul
Note: Le routeur ne peut pas dire si les clients tournent ou pas. Chacun doit pouvoir gérer une demande d'arrêt d'une application qui ne tourne pas sans faire d'histoires.
Idem pour le lancement d'un client déjà démarré.
New property clientApp.0.uninstallargs=truc machin uninstall bidule
Si présente, la classe sera appelée avec ces arguments juste avant la suppression de $PLUGIN
Toutes les tâches de désinstallation sont appelées avec un délais nul
New property clientApp.0.classpath=$I2P/lib/truc.muche,$PLUGIN/lib/bidule.jar
L'exécutable du greffon devra faire une substitution de variable dans les lignes des
les arguments et les stopargs de la façon suivante :
$I2P => dossier d'installation de base d'I2P;
$CONFIG => dossier de configuration d'i2p (habituellement ~/.i2p)
$PLUGIN => le dossier d'installation du greffon (habituellement ~/.i2p/plugins/appname)
(Voir les remarques importantes sur les scripts d'exécution shell ou les programmes externes)
Ces applications avec des tâches de fond doivent mettre en œuvre un ServletContextListener (voir les exemples de seedless ou i2pbote), ou écraser le destroy() dans le servlet, pour qu'elles puissent être arrêtées. À partir de la version 0.7.12-3 du routeur, les applications web de console sont toujours arrêtées avant d'être redémarrées pour que le développeur n'ait pas à se soucier des instances multiples, si jamais il y en a. À partir de cette même version, les webapps sont arrêtées lorsque le routeur est arrêté.
Ne fournissez pas de bibliothèques jars dans les webapps ; placez-les dans lib/ avec un classpath dans webapps.config. Vous pourrez ainsi faire des installations et des mises à jours séparées, où ces dernières ne contiendront pas de bibliothèques.
N'incluez pas de fichiers .java ou de .jsp ; sinon, jetty les recompilera à l'installation.
Pour l'instant, une webapp qui a besoin d'ajouter un des fichiers classpath dans $PLUGIN doivent avoir le même nom que que le greffon. Par exemple, la webapp du greffon 'truc' doit s'appeler truc.war.
La façon d'ajouter un greffon à un site eep n'est pas très claire. Le routeur n'a aucune jonction au site eep, l'état démarré ou arrêté de celui-ci lui est inconnu, et il peut y en avoir plusieurs. Le mieux est de lancer vos propres instances Jetty et I2PTunnel pour un nouvel eepsite.
Il peut instancier un nouvel I2PTunnel (comme comme le fait la ligne de commande i2ptunnel), mais bien sûr il ne sera pas visible dans le GUI i2ptunnel, qui est une instance différente. Ça n'est pas un problème. Vous pouvez ensuite arrêter et démarrer i2ptunnel et Jetty ensemble.
Ne comptez donc pas sur le routeur pour fusionner ça avec un site eep préexistant. Ça ne fonctionnera sûrement pas. Démarrez un nouvel I2PTunnel et un nouveau Jetty depuis le fichier clients.config. Les meilleurs exemples sont ceux des greffons zzzot et pebble, disponibles sur page greffons de zzz.
Comment réaliser une substitution de path dans jetty.xml? Voir les exemples de zzzot et pebble.
Le routeur ne dispose d'aucun moyen de contrôle de l'état des clients démarrés via clients.config. L'auteur du greffon doit gérer de multiples arrêts/démarrages, de façon fiable si possible, en gardant une table de trace d'état, ou avec les PID, etc… Évitez de tracer et de gérer les exceptions lors des multiples arrêts/démarrages, comme pour les demandes d'arrêt sans démarrage préalable. Depuis la v0.7.12-3, les greffons sont arrêtés avec le routeurs, ce qui veut dire que tous les clients avec des stopargs dans clients.config seront appelés, qu'il aient ou non été préalablement démarrés.
Pour exécuter des scripts shell ou d'autres programmes externes, voir zzz.i2p
Pour fonctionner sur Windows et Linux, écrivez une petite classe Java qui vérifie le type de SE, puis exécutez ShellCommand sur un .bat ou un .sh que vous fournissez vous-même.
Quand le routeur s'arrête, il n'arrête pas les programmes externes, et à contrario, une seconde copie sera lancée au démarrage du routeur. Pour empêcher ça, vous pourriez écrire une classe wrapper ou un script shell qui ferait le classique enregistrement du PID dans un fichier de PID, et le vérifier au démarrage.
i2p.jar, router.jar, jbigi.jar, sam.jar, mstreaming.jar, streaming.jar, i2ptunnel.jar, org.mortbay.jetty.jar, javax.servlet.jar, jasper-compiler.jar, jasper-runtime.jar, commons-logging.jar, commons-el.jar, wrapper.jar, systray.jar, systray4j.jar
Rien de non listé ci-dessus ne devrait se trouver dans le classpath de personne, même si l'avez dans le classpath de VOTRE version d'i2p. Si vous avez besoin d'un jar non listé ci-dessus, ajoutez $I2P/lib/truc.jar au classpath indiqué dans les fichiers clients.config ou webapps.config de votre greffon.
Précédemment, une entrée classpath indiquée dans clients.config était ajoutée au classpath de la JVM. Cependant ceci à été corrigé depuis la version 0.7.13-3 en utilisant les chargeurs de classes, et maintenant, conformément à ce qui était prévu dès l'origine, le classpath indiqué dans clients.config ne concerne que la tâche spécifique. Voir la section sur le plantage de la JVM plus bas, et cette page sur zzz.i2p pour plus de détails. En conséquence, indiquez le classpath intégral requis pour chaque client.
Si votre greffon n'a pas besoin de la 1.6 :
Si votre greffon nécessite la v1.6:
La JVM a tendance à planter lors de mises à jour des jars d'un greffon si celui-ci était en cours d'exécution quand i2p a été lancé (même si le greffon a été arrêté après). Ça pourrait avoir été corrigé par l'utilisation du chargeur de classes dans la version 0.7.13-3, mais peut-être pas. À tester ultérieurement.
Le plus sûr est de concevoir votre greffon avec le jar dans le war (pour une application web), ou d'exiger un redémarrage après la mise à jour, ou ne pas mettre à jour les jar de votre greffon.
De part le fonctionnement des class loaders dans une webapp, il _pourrait_ être sûr d'avoir des jars externes si vous indiquez le classpath dans le fichier webapps.config. Plus de tests sont nécessaires pour vérifier ce point. N'indiquez pas le classpath avec un client factice dans le fichier clients.config s'il n'est nécessaire que pour une webapp - utilisez plutôt webapps.config.
Le moins sûr, et apparemment source de la plupart des plantages, sont les clients avec les jars du greffon indiqués dans le classpath du fichier clients.config.
Rien de tout ceci ne devrait poser de problèmes sur une installation initiale - vous ne devriez même jamais avoir à demander un redémarrage pour une installation initiale d'un greffon. {% endblock %}