Diese Seite wurde zuletzt im August 2010 aktualisiert und bezieht sich auf die Routerversion (I2P-Version) 0.8.
Dieses Dokument beschreibt das XPI2P-Dateiformat (in Anlehnung an die XPI-Dateien von Firefox, aber mit einer einfachen Beschreibungsdatei namens plugin.config statt der XML-Datei install.rdf). Dieses Dateiformat kommt sowohl bei der Erstinstallation als auch beim Aktualisieren von Zusatzprogrammen zum Einsatz.
Des weiteren wird in diesem Dokument erklärt, wie der I2P-Router Zusatzprogramme installiert, sowie Richtlinien für die Entwicklung neuer Zusatzprogramme aufgeführt.
Die Grundstruktur des XPI2P-Formats ist dieselbe wie bei der Datei i2pupdate.sud (der Routeraktualisierungsdatei); Benutzer können aber Zusatzprogramme auch dann installieren, wenn dem Router der Signierschlüssel noch nicht bekannt ist.
Die hier beschriebene Verzeichnisstruktur (innerhalb der XPI2P-Datei) erlaubt es, folgende Arten von Zusatzprogrammen zu installieren:
Zusatzprogramme installieren alle ihre Dateien in ~/.i2p/plugins/Name/ (%APPDIR%\I2P\plugins\Name\ unter Windows). Der Router verwehrt Installationen in andere Verzeichnisse; es ist Zusatzprogramm jedoch nach dem Start möglich, auf Bibliotheken in anderen Verzeichnissen zuzugreifen.
Dies ist lediglich eine Maßnahme, um die Installation, Deinstallation und Aktualisierung zu vereinfachen und Konflikte zwischen Zusatzprogrammen zu verhindern.
Wenn jedoch ein Zusatzprogramm einmal läuft, ist praktisch keine Abschottung oder Absicherung zwischen Zusatzprogrammen und dem Router gegeben. Zusatzprogramme laufen in derselben JVM und mit den gleichen Rechten wie der Router; sie haben vollen Zugriff auf das Dateisystem, den Router, alle Rechte zur Programmausführung usw.
Beispiel.xpi2p ist eine SUD-Datei mit folgendem Inhalt:
Ein Standard-SUD-Vorspann (Header), der den Zip-Daten vorangeht und folgenden Inhalt hat: 40 Byte: DSA-Signatur 16 Byte: Zusatzprogrammversion in UTF-8, wenn nötig mit Nullen aufgefüllt Eine Zip-Datei mit folgendem Inhalt: plugin.config (PFLICHTDATEI) : (Standard-I2P-Konfigurationsdatei in UTF-8, die Zeilen im Format Parameter=Wert enthält; Kommentare beginnen mit #) Enthält die folgenden Einträge: (* = Pflichteintrag) In einer Aktualisierungsdatei müssen die ersten drei Einträge denen in der Installionsdatei entsprechen. *name: Name des Programms und gleichzeitig das Installationsverzeichnis Bei betriebssystemabhängigen Zusatzprogrammen werden entsprechende Namenszusätze empfohlen, z.B. beispiel-windows und beispiel-linux *key: Öffentlicher DSA-Schlüssel (172 B64-Zeichen mit einem '=' am Ende) *signer: Signierer (Empfehlung: deinname@mail.i2p) *version: Programmversion. Muss in einem Format, das der VersionComparator versteht, angegeben werden, z.B. 1.2.3-4) - Höchstens 16 Byte (muss der Version im SUD-Vorspann entsprechen) - Erlaubte Trennzeichen sind '.', '-' und '_' - In Aktualisierungsdateien muss die Version höher als die der bereits installierten Version sein Folgende Einträge werden, falls vorhanden, auf der Seite configclients.jsp angezeigt: - date: Java-Zeit als long-Zahl - author: Autor; Empfehlung: deinname@mail.i2p - websiteURL: Adresse der Zusatzprogrammwebseite (http://beispiel.i2p/) - updateURL: Die Adresse der Aktualisierungsdatei (http://beispiel.i2p/beispiel.xpi2p) Die Bytes 41-56 von dieser URL werden zur Prüfung auf neue Versionen ausgelesen ( Sollte beim Laden der URL die installierte Versionsnummer z.B. in der Form ?currentVersion=1.2.3?... mitgesendet werden? Nein, wenn die derzeitige Versionsnummer in der URL enthalten sein soll, kann der Programmierer sie selber in der Konfigurationsdatei in die URL einbauen. Bei einem Versionswechsel muss daran gedacht werden, auch die URL zu ändern) description: Programmbeschreibung description_xx: Programmebschreibung in der Sprache mit dem Kürzel xx license: Die Lizenz, unter der das Zusatzprogramm vertrieben wird disableStop=true Voreinstellung ist „false“. Der Wert „true“ bewirkt, dass der Stoppknopf nicht angezeigt wird. Diese Einstellung ist zu wählen, wenn keine Webanwendungen und keine anderen Programme mit Stoppargumenten enthalten sind Folgende Einträge steuern die Darstellung eines Links im Übersichtskasten in der Routerkonsole (oben links): consoleLinkName: Dieser Name erscheint im Übersichtskasten consoleLinkName_xx: Name in der Sprache mit dem Kürzel xx consoleLinkURL: Die URL, z.B. /appname/index.jsp consoleLinkTooltip: Hilfeeinblendung über dem Konsolenlink (Seit I2P 0.7.12-6) consoleLinkTooltip_xx: Hilfeeinblendung in der Sprache xx (Seit I2P 0.7.12-6) Folgende Einstellungen beziehen sich auf die Installation: type: Die Art des Zusatzprogramms oder Zusatzmoduls (Anwendung, Konsolengestaltung, Sprache, Webanwendung usw.). Dieser Parameter ist nicht implementiert und ist wahrscheinlich überflüssig. min-i2p-version max-i2p-version min-java-version min-jetty-version max-jetty-version required-platform-OS: Benötigtes Betriebssystem. Nicht implementiert; wird evtl. in einer späteren I2P-Version angezeigt, aber nicht überprüft. other-requirements: Andere Installationsvoraussetzungen (nicht implementiert; wird evtl. in einer späteren I2P-Version angezeigt, aber nicht überpfüft) dont-start-at-install: Bei false wird das Zusatzprogramm nach der Installation automatisch gestartet, bei true nicht. False ist die Standardeinstellung. router-restart-required: Bei false erscheint nach der Installation eine Meldung, die darüber informiert, dass ein Routerneustart notwendig ist (der Router wird aber nicht automatisch neu gestartet). Bei true erscheint die Meldung nicht. Standardeinstellung ist false. update-only: Bei true bricht der Installationsvorgang ab, wenn nicht bereits eine Installation vorhanden ist. Standardeinstellung ist false. install-only: Bei true bricht der Installationsvorgang ab, wenn bereits eine Installation vorhanden ist. Standardeinstellung ist false. min-installed-version: Mindestens installierte Version, wenn es sich um eine Aktualisierung handelt max-installed-version: Höchstens installierte Version, wenn es sich um eine Aktualisierung handelt depends=plugin1,plugin2,plugin3: Die Zusatzprogramme plugin1, plugin2 und plugin3 werden von diesem Zusatzprogramm vorausgesetzt. Diese Einstellung wurde von Sponge vorgeschlagen und ist nicht implementiert (evtl. schwierig) depends-version=0.3.4,,5.6.7: Mindestversionen der vorausgesetzten Zusatzprogramme. Nicht implementiert. Die folgende Einstellung wird von Übersetzungs-Zusatzmodulen verwendet, ist aber noch nicht implementiert: langs=xx,yy,Klingon,...: Gibt die bereitgestellten Sprachen an (xx und yy sind die Landeskürzel) Die folgenden Verzeichnisse sind optional, es muss aber mindestens eines angegeben sein, damit das Zusatzprogramm etwas bewirkt. console/ locale/ Jar-Dateien mit neuen Resource-Bundles, die Übersetzungen f¨r mit der I2P-Grundinstallation mitgelieferte Anwendungen enthalten. Resource-Bundles für das Zusatzprogramm selber gehören in console/webapp/beispiel.war oder lib/beispiel.jar. themes/ Neue Gestaltungen für die Routerkonsole, jede in einem eigenen Unterverzeichnis webapps/ (Bitte wichtige Bemerkungen zu Webanwendungen unten beachten) War-Dateien Die War-Dateien werden nach erfolgter Installation gestartet, sofern dies nicht in webapps.config deaktiviert ist. Der Name der War-Datei muss nicht dem Zusatzprogrammnamen entsprechen. Die Namen der in der I2P-Grundinstallation enthaltenen War-Dateien sind aber nicht erlaubt. webapps.config Diese Datei ist im selben Format wie die webapps.config des Routers. Darüberhinaus können hier zusätzliche Jar-Dateien in $PLUGIN/lib/ oder $I2P/lib dem Webanwendungs-Klassenpfad hinzugefügt werden. Beispiel: webapps.warname.classpath=$PLUGIN/lib/beispiel.jar,$I2P/lib/irgendetwas.jar Hinweis: Derzeit werden die Einträge in der Klassenpfadzeile nur geladen, wenn <warname> dem Namen des Zusatzprogramms entspricht. Hinweis: Vor der Version 0.7.12-9 erwartete der Router plugin.warname.startOnLoad statt webapps.warname.startOnLoad. Wird die Kompatibilität mit äteren Routerversionen gewünscht, wird empfohlen beide Zeilen anzugeben (wenn der automatische Start deaktiviert werden soll). eepsite/ (Bitte wichtige Bemerkungen zu Eepsites unten beachten) cgi-bin/ docroot/ logs/ webapps/ jetty.xml Der Installationscode muss hier Variablen ersetzen, um den Pfad zu setzen. Der Ort und Name dieser Datei spielt keine Rolle, er muss nur in der clients.config gesetzt sein. Evtl. ist es bequemer, ein Verzeichnis höher zu gehen (so macht es das Zusatzprogramm zzzot). lib/ Hier können Jar-Dateien abgelegt werden und in einem Klassenpfad in console/webapps.config und/oder clients.config angegeben werden. clients.config (Diese Datei ist im selben Format wie die clients.config des Routers) Die hier angegebenen Anwendungen werden gestartet, wenn das Zusatzprogramm startet. Die Numerierung ist bei 0 zu beginnen (clientApp.0) und jeweils um 1 zu erhöhen. Neue Einstellung clientApp.0.stopargs=beispiel xxx stop yyy Diese Einstellung bewirkt, falls vorhanden, dass die Klasse mit den angegebenen Argumenten aufgerufen wird, um die Anwendung zu beenden. Alle Stoppaufrufe erfolgen ohne Verzögerung. Bemerkung: Der Router kann nicht feststellen, ob eine Anwendung gerade läft. Alle Anwendungen müssen daher damit rechnen, gestoppt zu werden, auch wenn die Anwendung gar nicht läft. Selbiges gilt für Anwendungen, die bereits gestartet sind. Neue Einstellung clientApp.0.uninstallargs=beispiel xxx uninstall yyy Diese Einstellung bewirkt, falls vorhanden, dass die Klasse mit den angegebenen Argumenten unmittelbar vor dem Löschen von $PLUGIN aufgerufen wird. Alle Stoppaufrufe werden ohne Verzögerung durchgeführt. Neue Einstellung clientApp.0.classpath=$I2P/lib/beispiel.xxx,$PLUGIN/lib/yyy.jar Der Router ersetzt Variablen in den args- und stopargs-Zeilen wie folgt: $I2P => I2P-Installations-Grundverzeichnis; $CONFIG => I2P-Konfigurationsverzeichnis (meist ~/.i2p) $PLUGIN => Das Installationsverzeichnis des Zusatzprogramms (meist ~/.i2p/plugins/<zusatzprogverzeichnis>) (Bitte wichtige Anmerkungen bzgl. der Ausführung von Shellskripten und externen Programmen weiter unten beachten)
Bei Konsolen-Webanwendungen mit Hintergrundverarbeitung wird angeraten, einen ServletContextListener zu implementieren (siehe Seedless oder I2P-Bote als Beispiele) oder destroy() im Servlet zu überschreiben, so dass die Anwendung richtig beendet werden kann. Seit der Routerversion 0.7.12-3 werden Konsolen-Webanwendungen immer gestoppt, bevor sie neu gestartet werden. Man braucht sich daher als Programmierer über mehrfach laufende Anwendungen keine Gedanken machen, wenn man den obigen Rat beherzigt. Außerdem werden seit der Routerversion 0.7.12-3 Konsolen-Webanwendungen vor dem Beenden des Routers gestoppt.
Jar-Bibliotheken nicht in die Webanwendung aufnehmen, sondern im Verzeichnis lib/ ablegen und in webapps.config den Klassenpfad entsprechend setzen. Vorteil: Es kann eine Installations- und eine Aktualisierungsdatei bereitgestellt werden; die Aktualisierungsdatei kommt ohne die Jar-Bibliotheken aus.
Keine Java- oder JSP-Dateien einbinden, sonst kompiliert sie Jetty bei der Installation neu.
Derzeit müssen Webanwendungen den gleichen Namen wie das Zusatzprogramm (d.h. das gesamte Paket) haben, wenn Dateien im Verzeichnis $PLUGIN in den Klassenpfad sollen. Zum Beispiel muss eine Webanwendung im Zusatzprogramm xyz den Dateinamen xyz.war haben.
Es ist noch nicht geklärt, wie ein Zusatzprogramm in einer bestehenden Eepsite installiert werden soll. Der Router kann nicht ohne weiteres auf die Eepsite zugreifen, die Eepsite könnte gerade angehalten sein und es könnten auch mehrere vorhanden sein. Besser ist es, eine eigene Jetty- und I2PTunnel-Instanz zu starten und dadurch eine ganz neue Eepsite zu schaffen.
Der Router könnte zwar einen neuen I2PTunnel starten (ählich wie es die I2PTunnel-Kommandozeilenanwendung tut), dieser würde aber nicht in der I2PTunnel-Weboberfläche auftauchen, da es sich um eine andere Instanz handelt. Das stört aber nicht weiter, denn man kann dann I2PTunnel und Jetty zusammen starten und beenden.
Es ist also unwahrscheinlich, dass der Router irgendwann die Fähigkeit, eine Zusatz-Eepsite mit einer existierenden zu verbinden, erhält. Es wird dazu geraten, einen neuen I2PTunnel mitsamt Jetty aus der clients.config zu starten. Die besten Beispiele dafür sind die Zusatzprogramme zzzot und Pebble, verfügbar auf der Zusatzprogrammseite von zzz (englisch).
F: Wie erreicht man, dass Pfade in jetty.xml ersetzt werden? A: Siehe die Zusatzprogramme zzzot und Pebble als Beispiel.
Der Router kann nicht feststellen, ob eine Anwendung, die mittels clients.config gestartet wurde, gerade läft. Der Programmierer eines Zusatzprogramms muss daher darauf achten, dass mehrfache Start- oder Stoppaufrufe den Programmablauf nicht stören, sofern dies irgend möglich ist. Erreicht werden kann dies z.B. mit einer statischen Zustandstabelle, PID-Dateien ((PID = Prozessnummer) o.ä. Logausgaben oder Fehlermeldungen bei mehrfachen Start- oder Stoppaufrufen sollten vermieden werden. Gleiches gilt für Stoppaufrufe ohne vorherigen Startaufruf. Seit der Routerversion 0.7.12-3 werden Konsolen-Webanwendungen vor dem Beenden des Routers gestoppt, d.h. es werden alle Anwendungen, die in clients.config einen stopargs-Eintrag haben, beendet - egal ob sie gestartet wurden.
Zum Ausführen von Shellskripten und externen Programmen sei auf zzz.i2p (englisch) verwiesen.
Damit ein Skript sowohl unter Windows als auch Linux läft, empfiehlt es sich, eine kleine Java-Klasse, die den Betriebssystemtyp überprüft und die BAT- bzw. SH-Datei mittels ShellCommand ausführt, zu schreiben.
Externe Programme werden vom Router bei dessen Beendigung nicht gestoppt, und beim nächsten Routerstart wird eine zweite Instanz gestartet. Um das zu verhindern, kann man das Programm von einer Java-Klasse oder einem Shellskript ausführen lassen, die Prozessnummer (PID) in einer Datei speichern und beim nächsten Start überprüfen.
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
Alles, was nicht in der obigen Liste aufgeführt ist, kann nicht allgemein als vorhanden vorausgesetzt werden, auch wenn es im eigenen Klassenpfad vorhanden ist. Wenn eine Jar-Datei, die oben nicht aufgeführt ist, benötigt wird, fügt man $I2P/lib/beispiel.jar in den Klassenpfad in der clients.config oder webapps.config des Zusatzprogramms ein.
Anfangs waren Klassenpfadeinträge in der clients.config in der ganzen JVM (der virtuellen Java-Maschine) verfügbar. Seit der Version 0.7.13-3 ist der Klassenpfad in der clients.config nur in dem entsprechenden Ausführungsstrang (Thread) verfügbar, wie es auch ursprünglich beabsichtigt war. Dies wird mittels eines speziellen Klassenladers erreicht. Zu Details siehe auch den Abschnitt über JVM-Abstürze weiter unten und diesen Diskussionsstrang auf zzz.i2p. Es ist daher für jede Anwendung der volle Klassenpfad anzugeben.
Wenn ein Zusatzprogramm nicht auf 1.6 beschränkt sein soll,
Wenn ein Zusatzprogramm 1.6 erfordert,
Die JVM (virtuelle Java-Maschine) stürzt gelegentlich ab, wenn in einem Zusatzprogramm enthaltene Jar-Dateien aktualisiert werden und das Zusatzprogramm seit dem Start von I2P gestartet wurde (auch wenn es danach wieder beendet wurde). Dies ist möglicherweise durch den neuen Klassenlader in 0.7.13-3 behoben worden, könnte aber auch weiterhin bestehen und muss noch genauer untersucht werden.
Am sichersten ist es, wenn man im Zusatzprogramm die Jar-Datei in der War-Datei ausliefert (im Falle einer Webanwendung) oder nach der Aktualisierung für einen Neustart sorgt, oder die Jar-Dateien des Zusatzprogramms gar nicht aktualisiert.
Aufgrund der Funktionsweise von Klassenladern in Webanwendungen sind externe Jar-Dateien vermutlich ungefährlich, wenn der Klassenpfad in der webapps.config angegeben wird. Um darüber eine sichere Aussage treffen zu können, sind aber weitere Tests nötig. Es wird davon abgeraten, den Klassenpfad mit einer Pseudoanwendung in clients.config anzugeben, wenn er nur für eine Webanwendung benötigt wird; webapps.config ist in dem Fall der geeignete Ort.
Am problematischsten sind Anwendungen mit Jar-Dateien, die im Klassenpfad in der clients.config angegeben werden. Offenbar verursacht das die meisten Abstürze.
Bei der Erstinstallation tritt keines dieser Probleme auf, es ist also nicht nötig, nach der Erstinstallation eines Zusatzprogramms einen Neustart zu veranlassen. {% endblock %}