i2p.www/www.i2p2/pages/plugin_spec_fr.html

{% extends "_layout_fr.html" %}
{% block title %}Spécification des greffons I2P{% endblock %}
{% block content %}
Traduction de mai 2011. <a href="plugin_spec.html">Version anglaise actuelle</a>
<h2>
Spécification Version 0.16
2010-07-26
</h2>
<p> 
Mise à jour de juillet 2010 pour le routeur version 0.8.
<h3>Aperçu</h3>
<p> 
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.
<p>
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.
<p>
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.
<p>
La structure standard des répertoires permet l'installation des types de greffons suivants :
<ul>
<li>
	 applications web de console (webapps)
<li>
	 nouvel eepsite avec cgi-bin, webapps
<li>
	 thèmes de console
<li>
	 traductions de console
<li>
	 programmes Java
<li>
	 programmes Java dans une JVM séparée
<li>
	 Tout script shell ou programme
</ul>

<p>
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.

<p>
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.

<p>
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&hellip;
<h3>Détails</h3>
<p>
foo.xpi2p est un fichier sud contenant les données suivantes :
<pre>
En-tête standard .sud au début du fichier zip, contenant :
        La <a href="how_cryptography.html#DSA">signature DSA</a> à 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 (<a href="how_cryptography.html#DSA">clé publique DSA</a> 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?&hellip; 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)
</pre>


<h3>Tâches d'installation du greffon</h3>
Séquence d'installation.
<ul>

    <li>Téléchargement du fichier .xpi2p.</li>
    <li>Vérification de la signature du .sud par rapport au clés connues. En l'absence de correspondance, le .sud est 
	extrait, la clé est chargée à partir des propriétés, vérifiée et enregistrée.</li>
    <li>Vérification de l'intégrité du fichier zip.</li>
    <li>Extraction du fichier plugin.config.</li>
    <li>Vérification de la version d'I2P, pour assurer que le greffon peut fonctionner.</li>
    <li>Vérification qu'il ne s'agit pas d'un doublon d'une des application $I2P.</li>
    <li>Arrêt de l'éventuel greffon existant.</li>
    <li>Contrôle de l'inexistence du dossier d'installation si update=false, ou demande d'écrasement.</li>
    <li>Vérification de l'existence du dossier d'installation update=true, ou demande de création.</li>
    <li>Décompression du greffon dans appDir/plugins/name/</li>
    <li>Ajout d'une référence au greffon dans plugins.config</li>
</ul>

<h3>
Tâches du lanceur du greffon</h3>
Séquence de lancement du greffon.
tout d'abord, le fichier plugins.config est vérifié pour trouver quels greffons doivent être lancés.
Pour chacun :
<ul>
    <li>Vérification de clients.config, chargement et lancement de chacun (ajout des jars configurés au classpath).</li>
    <li>Vérification de console/webapp et console/webapp.config. chargement et lancement des éléments requis 
	(ajout des jars configurés au classpath).</li>
    <li>Ajout de console/locale/truc.muche au classpath de traduction, si présent.</li>
    <li>Ajout de console/theme au chemin de recherche de thèmes, si présent.</li>
    <li>Ajout du lien au panneau de contrôle.</li>
</ul>

<h3>
Remarques sur les applications web de console</h3>
<p>
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é.
<p>
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.
<p>
N'incluez pas de fichiers .java ou de .jsp ; sinon, jetty les recompilera à l'installation.
<p>
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.


<h3>
Remarques sur les eepsite
</h3>
<p>
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.
<p>
 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.
<p>
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 <a href="http://stats.i2p/i2p/plugins/">page greffons de zzz</a>.
<p>
Comment réaliser une substitution de path dans jetty.xml? Voir les exemples de zzzot et pebble.


<h3>
Remarques sur l'arrêt/démarrage du client
</h3>
<p>
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&hellip; É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.


<h3>
Remarques sur les scripts Shell et les programmes externes
</h3>
<p>
Pour exécuter des scripts shell ou d'autres programmes externes, voir <a href="http://zzz.i2p/topics/141">zzz.i2p</a>
<p>
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.
<p>
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.




<h3>
Autres conseils pour les greffons
</h3>
<ul>
<li>
Pour développer facilement, voir un générateur de fichier xpi2p, dans monotone à la branche i2p.scripts, ou les échantillons d'exemples de greffons sur la page de zzz<li>
Pack200 est fortement recommandé pour les jars et les wars des greffons, cela réduit leur taille d'environ 60 à 65%.
Voir exemple sur la page de zzz.
La décompression Pack200 est supportée depuis le routeur version 0.7.11-5, c'est à dire quasiment tous les routeurs qui 
supportent les greffons.

<li>
 Les greffons ne doivent pas tenter d'écrire dans le dossier $I2P car il est potentiellement en lecture seule, et 
qu'en tous les cas ça n'est pas une bonne pratique.
<li>
 Les greffons peuvent écrire dans le dossier $CONFIG, mais seul le stockage de fichiers dans $PLUGIN est 
recommandé. Tous les fichiers de $PLUGIN sont supprimés à la désinstallation. Les fichiers situés ailleurs ne sont 
pas supprimés, à moins que le greffon ne le spécifie explicitement par les 'uninstallargs' d'exécution d'un client 
indiqués dans le fichier clients.config. Si l'utilisateur veut sauvegarder des données à la désinstallation, il 
peut le faire avec les branchements des 'uninstallargs'.
<li>
 Le dossier $CWD peut se trouver n'importe où ; ne considérez pas qu'il se trouve à un endroit particulier, 
n'essayez pas de lire ou écrire des fichiers dans le chemin relatif $CWD.
<li>
 Le programmes Java doivent pouvoir déterminer où ils se trouvent avec les 'getters' de I2PAppContext.
<li>
 Le dossier des greffons est I2PAppContext.getGlobalContext().getAppDir().getAbsolutePath() + "/plugins/" + nom de 
l'application, ou indiquez un argument $PLUGIN dans la ligne args du fichier clients.config. Il n'y a pas de moyen 
fiable pour trouver les dossiers d'installation d'i2p, de configuration ou de greffons sans utiliser l'API de contexte 
d'i2p.jar.
<li>
 Voir <a href="http://zzz.i2p/topics/16">Comment faire</a> pour générer les clés de signature et les clés de 
génération/vérification, et les fichiers .sud.
<li>
 Tous les fichiers de configuration doivent être encodés en UTF-8.
<li>
 Pour l'exécution dans une JVM séparée, utilisez ShellCommand avec java -cp truc:muche:bidule ma.pricipale.classe arg1 arg2 arg3.
Évidement, il sera alors bien plus difficile d'arrêter le greffon&hellip;
Mais cela reste possible en jouant avec les fichiers PID.
<li>
 En tant qu'alternative aux stopargs dans clients.config, un client Java peut enregistrer un lien d'arrêt avec 
I2PAppContext.addShutdownTask(). Mais ça n'arrêtera pas le greffon lors d'une mise à jour, donc les stopargs restent 
préférables. De plus, définissez en mode service toutes les tâches créées.
<li>
 N'incluez pas de classes dupliquant celles de l'installation standard. Améliorez les classes si nécessaire.
<li>
 Faites attention aux définitions des divers classpath dans wrapper.config entre les installations anciennes et 
nouvelles - voir la section 'classpath' plus bas.
<li>
 Les clients rejetterons les clés dupliquées avec des noms de clé différents, des noms de clés dupliqués avec des clés 
différentes, et des clés ou noms de clés différents dans les paquets de mises à jour. Sauvegardez vos clés de façon 
maniaque et paranoïaque. Ne les générez qu'une seule fois.
<li>
 Ne modifiez pas le fiichier plugin.config à l'exécution car il sera écrasé lors d'une mise à jour. Utilisez un fichier 
de configuration différent dans le dossier pour enregistrer la configuration d'exécution.
<li>
 En général, les greffons n'ont pas besoin d'accéder à $I2P/lib/router.jar. N'accédez pas aux classes du routeur, à 
moins que vous ne fassiez quelque-chose de particulier. Dans l'avenir, le routeur pourrait implémenter un classpath 
réservé pour les greffons, qui empêcherait l'accès à ses propres classes.
<li>
Comme chaque numéro de version doit être supérieur à celui de le version précédente, vous pouvez améliorer vos scripts 
de développement en ajoutant un numéro de développement à la fin du numéro de version. C'est pratique pour les tests. 
La plupart des greffons de zzz utilisent cette méthode : regardez build.xml à titre d'exemple.
<li>
Les greffons ne doivent jamais invoquer System.exit().
<li>
Merci de respecter les licences en vous conformant aux exigences de licences pour tout logiciel que vous fournissez.
</ul>

<h3>
Classpaths
</h3>

Vous pouvez considérer que les jars suivants dans $I2P/lib sont dans le classpath standard pour toutes les 
installations dI2P, quel que soit l'âge de l'installation d'origine :
<p>
 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
<p>

 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.
<p>
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 <a href="http://zzz.i2p/topics/633">cette page sur zzz.i2p</a> 
pour plus de détails. En conséquence, indiquez le classpath intégral requis pour chaque client.


<h3>
Notes sur les versions de Java
</h3>
Bien que la plupart des utilisateurs d'I2P utilisent une JVM 1.6 (6.0), nous prenons en charge la version 1.5 (5.0) et 
les plus récentes.
À moins que vous n'ayez besoin de fonctionnalités de la v1.6, vous devriez créer vos greffons avec la v1.5 pour 
garantir le fonctionnement à ceux qui l'utilisent.
<p>
Si votre greffon <b>n'a pas besoin de la 1.6</b> :
<ul>
<li>
Assurez-vous que tous les fichiers java et jsp sont compilés avec source="1.5" target="1.5".
<li>
Assurez-vous aussi que toutes les bibliothèques jars fournies sont pour la v1.5 ou plus ancienne.
<li>
Si vous utilisez pack200, toute classe 1.6 dans un jar fera que pack200 créera un paquet au format 1.6 pack format, et 
l'installation du greffon échouera sur un système en v1.5 en générant le message erroné suivant : "Le greffon est 
corrompu".
</ul>

<p>
Si votre greffon <b>nécessite la v1.6</b>:
<ul>
<li>
Précisez-le expressément sur votre page de téléchargement.
<li>
Ajoutez min-java-version=1.6 dans votre ficher plugin.config
<li>
Si vous utilisez pack200, l'installation du greffon sur un système en v1.5 échouera et retournera un message erroné "Le 
greffon est corrompu".
</ul>


<h3>
La JVM se plante en mise à jour
</h3>
Note - tout devrait être résolu à l'heure actuelle.
<p>
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.
<p>
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.
<p>
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.
<p>
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.

<p>
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 %}