478 lines
26 KiB
HTML
478 lines
26 KiB
HTML
{% extends "_layout.html" %}
|
|
{% block title %}Technische Beschreibung I2P-Zusatzprogramme{% endblock %}
|
|
{% block content %}
|
|
<h2>
|
|
Technische Beschreibung, Version 0.16
|
|
26.7.2010
|
|
</h2>
|
|
<p>
|
|
Diese Seite wurde zuletzt im August 2010 aktualisiert und bezieht sich auf die Routerversion (I2P-Version) 0.8.
|
|
<h3>Übersicht</h3>
|
|
<p>
|
|
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.
|
|
<p>
|
|
Des weiteren wird in diesem Dokument erklärt, wie der I2P-Router Zusatzprogramme installiert, sowie Richtlinien für
|
|
die Entwicklung neuer Zusatzprogramme aufgeführt.
|
|
<p>
|
|
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.
|
|
<p>
|
|
Die hier beschriebene Verzeichnisstruktur (innerhalb der XPI2P-Datei) erlaubt es, folgende Arten von Zusatzprogrammen
|
|
zu installieren:
|
|
<ul>
|
|
<li>
|
|
Webanwendungen
|
|
<li>
|
|
Neue Eepsites mit cgi-bin und Webanwendungen
|
|
<li>
|
|
Konsolengestaltungen
|
|
<li>
|
|
Konsolenübersetzungen
|
|
<li>
|
|
Java-Programme
|
|
<li>
|
|
Java-Programme, die in einer eigenen JVM laufen
|
|
<li>
|
|
Beliebiges Shellskripte oder Programme
|
|
</ul>
|
|
|
|
<p>
|
|
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.
|
|
|
|
<p>
|
|
Dies ist lediglich eine Maßnahme, um die Installation, Deinstallation und Aktualisierung zu vereinfachen
|
|
und Konflikte zwischen Zusatzprogrammen zu verhindern.
|
|
|
|
<p>
|
|
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.
|
|
|
|
<h3>Details</h3>
|
|
<p>
|
|
Beispiel.xpi2p ist eine SUD-Datei mit folgendem Inhalt:
|
|
<pre>
|
|
Ein Standard-SUD-Vorspann (<i>Header</i>), der den Zip-Daten vorangeht und folgenden Inhalt hat:
|
|
40 Byte: <a href="how_cryptography.html#DSA">DSA-Signatur</a>
|
|
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: <a href="how_cryptography.html#DSA">Öffentlicher DSA-Schlüssel</a> (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)
|
|
</pre>
|
|
|
|
|
|
<h3>Ablauf der Installation eines Zusatzprogrammes
|
|
</h3>
|
|
<ul>
|
|
|
|
<li>
|
|
Herunterladen der xpi2p-Datei
|
|
<li>
|
|
Prüfen der SUD-Signatur anhand der gespeicherten Schlüssel, oder falls kein Schlüssel vorhanden:<br/>
|
|
- auspacken, öff. Schlüssel aus der Konfiguration lesen, überprüfen und Schlüssel speichern
|
|
<li>
|
|
Prüfen, ob die ZIP-Datei unversehrt ist
|
|
<li>
|
|
Die Datei plugin.config auspacken
|
|
<li>
|
|
Mindest- und Höchstversion usw. überprüfen
|
|
<li>
|
|
Prüfung, ob eine der Webanwendungen mit einer in $I2P namensgleich ist
|
|
<li>
|
|
Vorhandenes Zusatzprogramm stoppen
|
|
<li>
|
|
Wenn update=false ist: Prüfung, ob das Installationsverzeichnis bereits existiert; wenn ja, Benutzer fragen
|
|
<li>
|
|
Wenn update=true ist: Prüfung, ob das Installationsverzeichnis bereits existiert; wenn nein, Benutzer fragen
|
|
<li>
|
|
In <tt>appDir/plugins/name/</tt> auspacken
|
|
<li>
|
|
Zu plugins.config hinzufügen
|
|
</ul>
|
|
|
|
<h3>
|
|
Ablauf des Startens eines Zusatzprogrammes
|
|
</h3>
|
|
Anhand plugins.config wird festgestellt, welche gestartet werden müssen.
|
|
Dann geschieht jeweils folgendes:
|
|
<ul>
|
|
<li>
|
|
Die Einträge der clients.config (des Zusatzprogramms) werden geladen und gestartet (Jar-Dateien werden in den Klassenpfad aufgenommen)
|
|
<li>
|
|
Die Einträge in console/webapp and console/webapp.config werden geladen und gestartet (Jar-Dateien werden in den Klassenpfad aufgenommen)
|
|
<li>
|
|
Falls vorhanden, wird console/locale/xxxxx.jar in den Übersetzungs-Klassenpfad aufgenommen
|
|
<li>
|
|
Falls vorhanden, wird console/theme in den Suchpfad für Konsolengestaltungen aufgenommen
|
|
<li>
|
|
Im Übersichtskasten (oben links in der Konsole) wird ein entspr. Link hinzugefügt
|
|
</ul>
|
|
|
|
<h3>
|
|
Bemerkungen zu Konsolen-Webanwendungen
|
|
</h3>
|
|
<p>
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
Keine Java- oder JSP-Dateien einbinden, sonst kompiliert sie Jetty bei der Installation neu.
|
|
<p>
|
|
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.
|
|
|
|
|
|
<h3>
|
|
Bemerkungen zu Eepsites
|
|
</h3>
|
|
<p>
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
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 <a href="http://stats.i2p/i2p/plugins/">der Zusatzprogrammseite von zzz</a> (<i>englisch</i>).
|
|
<p>
|
|
F: Wie erreicht man, dass Pfade in jetty.xml ersetzt werden?
|
|
A: Siehe die Zusatzprogramme zzzot und Pebble als Beispiel.
|
|
|
|
<h3>
|
|
Bemerkungen zum Starten und Stoppen von Anwendungen
|
|
</h3>
|
|
<p>
|
|
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.
|
|
|
|
|
|
<h3>
|
|
Bemerkungen zu Shellskripten und externen Programmen
|
|
</h3>
|
|
<p>
|
|
Zum Ausführen von Shellskripten und externen Programmen sei auf <a href="http://zzz.i2p/topics/141">zzz.i2p</a> (<i>englisch</i>) verwiesen.
|
|
<p>
|
|
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.
|
|
<p>
|
|
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.
|
|
|
|
|
|
<h3>
|
|
Weitere Richtlinien für Zusatzprogramme
|
|
</h3>
|
|
<ul>
|
|
<li>
|
|
Zum Erzeugen von XPI2P-Dateien siehe den MTN-Zweig i2p.scripts oder eines der Beispiele auf der Zusatzprogrammseite von zzz.
|
|
<li>
|
|
Das Komprimieren von Jar- und War-Dateien mit Pack200 ist sehr empfehlenswert. Zusatzprogramme werden dadurch im allgemeinen
|
|
60-65% kleiner.
|
|
Die Zusatzprogramme auf der Seite von zzz können hier als Beispiele dienen.
|
|
Das Dekomprimieren von Pack200-Dateien wird seit der Routerversion 0.7.11-5 unterstützt, d.h. praktisch alle Router,
|
|
die Zusatzprogramme unterstützen, kommen damit klar.
|
|
|
|
<li>
|
|
Zusatzprogramme sollten nicht im Verzeichnisbaum $I2P schreiben, da Schreibrechte nicht unbedingt vorhanden sind und dies
|
|
ohnehin grundsätzlich vermieden werden sollte.
|
|
<li>
|
|
Zusatzprogramme dürfen in $CONFIG schreiben; es wird aber empfohlen, alle Daten in $PLUGIN abzulegen.
|
|
Alle Dateien in $PLUGIN werden bei der Deinstallation gelöscht.
|
|
Dateien in anderen Verzeichnissen werden bei der Deinstallation nur dann gelöscht, wenn das Zusatzprogramm mit einem
|
|
uninstallargs-Eintrag in clients.config selber dafür sorgt.
|
|
Ggf. kann das uninstallargs-Programm den Benutzer fragen, ob die Daten erhalten bleiben sollen.
|
|
|
|
<li>
|
|
$CWD (das Arbeitsverzeichnis) kann überall sein. Es ist also falsch, von einem bestimmten Arbeitsverzeichnis auszugehen
|
|
oder Dateien relativ zu $CWD zu lesen oder zu schreiben.
|
|
<li>
|
|
Um in Java-Programmen die verschiedenen Verzeichnisse ermitteln zu können, gibt es die get...Dir-Methoden in I2PAppContext.
|
|
<li>
|
|
Das Zusatzprogrammverzeichnis erhält man mit <tt>I2PAppContext.getGlobalContext().getAppDir().getAbsolutePath() + "/plugins/" + appname</tt>,
|
|
oder indem man $PLUGIN als Argument in the args-Zeile in clients.config angibt.
|
|
Das I2P-Installationsverzeichnis, das Konfigurationsverzeichnis und das Zusatzprogrammverzeichnis lassen sich einzig über
|
|
die Kontext-Klassen in i2p.jar verlässlich ermitteln.
|
|
<li>
|
|
Zum Erzeugen von Signierschlüsseln, zum Überprüfen von Signaturen und zum Erzeugen von SUD-Dateien siehe <a href="http://zzz.i2p/topics/16">hier</a>.
|
|
<li>
|
|
Alle Konfigurationsdateien müssen in UTF-8 kodiert sein.
|
|
<li>
|
|
Um ein Programm in einer separaten JVM (Virtuelle Java-Maschine) laufen zu lassen, ruft man
|
|
<tt>ShellCommand</tt> mit <tt>java -cp xxx:yyy:zzz abc.beispiel.class arg1 arg2 arg3</tt> auf.
|
|
Das Beenden des Programms wird dadurch schwieriger; es empfiehlt sich hier wieder, die Prozessnummer in einer Datei
|
|
zu speichern.
|
|
<li>
|
|
Als Alternative zum stopargs-Parameter in clients.config gibt es für Java-Programme die Möglichkeit,
|
|
mittels I2PAppContext.addShutdownTask() bei der Routerbeendigung Aufräumarbeiten verrichten zu lassen und
|
|
externe Programme zu beenden.
|
|
Bei der Aktualisierung eines Zusatzprogrammes wird dieses aber dann nicht beendet, weshalb stopargs vorzuziehen ist.
|
|
Alle Ausführungsstränge (<i>Threads</i>) sollten im Daemon-Modus laufen.
|
|
<li>
|
|
Es ist darauf zu achten, keine Klassenbezeichner zu wählen, die mit den Klassen- und Paketnamen in der Grundinstallation
|
|
kollidieren. Außerdem sollte in der Grundinstallation vorhandene Funktionalität nicht neu implementiert werden,
|
|
sondern die jeweilige(n) Klasse(n) vererbt werden.
|
|
<li>
|
|
Vorsicht mit Klassenpfaden in der wrapper.config, diese werden in alten Versionen anders behandelt. Siehe den Abschnitt über
|
|
Klassenpfade weiter unten.
|
|
<li>
|
|
Gleiche Signierschlüssel mit abweichenden Namen werden abgewiesen, ebenso wie gleiche Namen für
|
|
unterschiedliche Schlüssel und abweichende Schlüssel / Namen in Aktualisierungspaketen.
|
|
Deshalb Signierschlüssel sicher verwahren und sie nur einmal erzeugen.
|
|
<li>
|
|
Plugin.config nicht zur Laufzeit ver&auuml;ndern, da sie beim Aktualisieren überschrieben wird.
|
|
Besser ist es, Laufzeitdaten in einer anderen Konfigurationsdatei im gleichen Verzeichnis zu speichern.
|
|
<li>
|
|
In der Regel ist es nicht notwendig, dass Zusatzprogramme auf $I2P/lib/router.jar zugreifen.
|
|
In einer späteren Version wird der Router evtl. den Klassenpfad für Zusatzprogramme einschränken und den Zugriff auf Routerklassen verhindern.
|
|
Deshalb sollte möglichst nicht auf Routerklassen zugegriffen werden.
|
|
<li>
|
|
Wie erwähnt muss jede Version höher als die vorherige sein. Zu diesem Zweck kann man im Kompilierskript eine fortlaufende Nummer an die Versionsbezeichnung anhängen.
|
|
Das Testen wird dadurch erleichtert. Die meisten Zusatzprogramme von zzz verfahren so; als Beispiel kann man sich an der jeweiligen build.xml orientieren.
|
|
<li>
|
|
Zusatzprogramme dürfen unter keinen Umständen System.exit() aufrufen.
|
|
<li>
|
|
Wenn Fremdsoftware eingebunden wird, bitte die Lizenzbedingungen einhalten.
|
|
|
|
</ul>
|
|
|
|
<h3>
|
|
Klassenpfade
|
|
</h3>
|
|
|
|
Die folgenden Jar-Dateien in $I2P/lib sind bei allen I2P-Installationen im Standard-Klassenpfad vorhanden, egal wann I2P ursprünglich installiert wurde:
|
|
<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>
|
|
|
|
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.
|
|
<p>
|
|
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 (<i>Thread</i>)
|
|
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 <a href="http://zzz.i2p/topics/633">diesen Diskussionsstrang auf zzz.i2p</a>.
|
|
Es ist daher für jede Anwendung der volle Klassenpfad anzugeben.
|
|
|
|
|
|
<h3>
|
|
Bemerkungen zu Java-Versionen
|
|
</h3>
|
|
Die meisten Benutzer lassen I2P zwar unter Java 1.6 (auch unter dem Namen Java 6 bekannt),
|
|
I2P unterstützt aber auch Java 1.5 (Java 5).
|
|
Wenn keine 1.6-spezifische Funktionalität benötigt wird, sollten Zusatzprogramme
|
|
so geschrieben werden, dass sie auch unter 1.5 laufen.
|
|
<p>
|
|
Wenn ein Zusatzprogramm <b>nicht auf 1.6 beschränkt sein soll</b>,
|
|
<ul>
|
|
<li>
|
|
müssen alle Java- und JSP-Dateien mit der Einstellung <tt>source="1.5" target="1.5"</tt> kompiliert werden, und
|
|
<li>
|
|
alle eingebundenen Jar-Bibliotheken müssen ebenfalls für 1.5 kompiliert sein.
|
|
<li>
|
|
Wenn Pack200 eingesetzt wird, führen 1.6-Klassen in Jar-Dateien dazu, dass Pack200 das neuere 1.6-Packformat
|
|
verwendet und die Installation des Zusatzprogramms unter Java 1.5 mit der irreführenden Meldung „Zusatzprogramm ist korrupt“
|
|
scheitert.
|
|
</ul>
|
|
|
|
<p>
|
|
Wenn ein Zusatzprogramm <b>1.6 erfordert</b>,
|
|
<ul>
|
|
<li>
|
|
Sollte darauf auf der Seite, von der das Programm bezogen werden kann, hingewiesen werden, und
|
|
<li>
|
|
Die Einstellung <tt>min-java-version=1.6</tt> in der plugin.config gesetzt werden.
|
|
<li>
|
|
Wenn Pack200 eingesetzt wird, schlägt die Installation des Zusatzprogramms unter Java 1.5 mit der
|
|
irreführenden Meldung „Zusatzprogramm ist korrupt“ fehl.
|
|
</ul>
|
|
|
|
|
|
<h3>
|
|
JVM-Abstürze beim Aktualisieren
|
|
</h3>
|
|
Bemerkung: Dies müsste inzwischen alles behoben sein.
|
|
<p>
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
Aufgrund der Funktionsweise von Klassenladern in Webanwendungen sind externe Jar-Dateien <b>vermutlich</b> 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.
|
|
<p>
|
|
Am problematischsten sind Anwendungen mit Jar-Dateien, die im Klassenpfad in der clients.config angegeben werden. Offenbar
|
|
verursacht das die meisten Abstürze.
|
|
|
|
<p>
|
|
Bei der Erstinstallation tritt keines dieser Probleme auf, es ist also nicht nötig, nach der Erstinstallation eines Zusatzprogramms
|
|
einen Neustart zu veranlassen.
|
|
|
|
{% endblock %}
|