i2p.www/i2p2www/pages/site/docs/plugins.html

{% extends "global/layout.html" %}
{% block title %}{% trans %}Plugins{% endtrans %}{% endblock %}
{% block lastupdated %}{% trans %}June 2012{% endtrans %}{% endblock %}
{% block accuratefor %}0.9{% endblock %}
{% block content %}
<h2>{% trans %}General Information{% endtrans %}</h2>
<p>{% trans -%}
The I2P network includes a plugin architecture
to support both easy development and installation of new plugins.
{%- endtrans %}</p>

<p>{% trans -%}
There are now plugins available that support distributed email, blogs, IRC
clients, distributed file storage, wikis, and more.
{%- endtrans %}</p>

<h3>{% trans -%}Adding Plugins To Your I2P Router{%- endtrans %}</h3>
<p>{% trans -%}
I2P Plugins can be installed by copying the plugin download URL onto
the appropriate section on the <a href="http://127.0.0.1:7657/configplugins">Router Console Plugin Configuration Page</a>.
{%- endtrans %}</p>

<p>{% trans -%}
Start by copying the plugin URL from the page where it is published.
{%- endtrans %}</p>
<img src="/_static/images/plugins/plugin-step-0.png">

<p>{% trans -%}
Then visit the plugin configuration page, which you can find linked on the console homepage.
{%- endtrans %}</p>
<img src="/_static/images/plugins/plugin-step-1.png">

<p>{% trans -%}
Paste in the URL and click the "Install Plugin" button.
{%- endtrans %}</p>
<img src="/_static/images/plugins/plugin-step-2.png">

<h3>{% trans -%}Benefits to i2p users and app developers:{%- endtrans %}</h3>

<ul>
<li>{% trans -%}
Easy distribution of applications
{%- endtrans %}</li>

<li>{% trans -%}
Allows innovation and use of additional libraries without worrying about
increasing the size of <code>i2pupdate.sud</code>
{%- endtrans %}</li>

<li>{% trans -%}
Support large or special-purpose applications that would never be bundled
with the I2P installation
{%- endtrans %}</li>

<li>{% trans -%}
Cryptographically signed and verified applications
{%- endtrans %}</li>

<li>{% trans -%}
Automatic updates of applications, just like for the router
{%- endtrans %}</li>

<li>{% trans -%}
Separate initial install and update packages, if desired, for smaller update downloads
{%- endtrans %}</li>

<li>{% trans -%}
One-click installation of applications. No more asking users to modify
<code>wrapper.config</code> or <code>clients.config</code>
{%- endtrans %}</li>

<li>{% trans -%}
Isolate applications from the base <code>$I2P</code> installation
{%- endtrans %}</li>

<li>{% trans -%}
Automatic compatibility checking for I2P version, Java version, Jetty
version, and previous installed application version
{%- endtrans %}</li>

<li>{% trans -%}
Automatic link addition in console
{%- endtrans %}</li>

<li>{% trans -%}
Automatic startup of application, including modifying classpath, without requiring a restart
{%- endtrans %}</li>

<li>{% trans -%}
Automatic integration and startup of webapps into console Jetty instance
{%- endtrans %}</li>

<li>{% trans pluginsite=i2pconv('plugins.i2p') -%}
Facilitate creation of 'app stores' like the one at
<a href="http://{{ pluginsite }}">{{ pluginsite }}</a>
{%- endtrans %}</li>

<li>{% trans -%}
One-click uninstall
{%- endtrans %}</li>

<li>{% trans -%}
Language and theme packs for the console
{%- endtrans %}</li>

<li>{% trans -%}
Bring detailed application information to the router console
{%- endtrans %}</li>

<li>{% trans -%}
Non-java applications also supported
{%- endtrans %}</li>
</ul>


<h3>{% trans %}Required I2P version{% endtrans %}</h3>
<p>{% trans %}0.7.12 or newer.{% endtrans %}</p>

<h3>{% trans %}Updating a  Plugin{% endtrans %}</h3>

<p>{% trans -%}
To update a plugin to the latest version, just click the update button on
<a href="http://127.0.0.1:7657/configclients.jsp#plugin">configclients.jsp</a>.
There is also a button to check if the plugin has a more recent version, as
well as a button to check for updates for all plugins.  Plugins will be checked
for updates automatically when updating to a new I2P release (not including dev
builds).
{%- endtrans %}</p>
<img src="/_static/images/plugins/plugin-update-0.png">


<h3>{% trans %}Development{% endtrans %}</h3>
<p>{% trans pluginspec=site_url('docs/spec/plugin'), zzz=i2pconv('zzz.i2p') -%}
See the latest <a href="{{ pluginspec }}">plugin specification</a>
{%- endtrans %}</p>

<p>{% trans pluginsite=i2pconv('plugins.i2p') -%}
See also the sources for plugins developed by various people.  Some plugins, such
as <a href="http://{{ pluginsite }}/plugins/snowman">snowman</a>, were developed
specifically as examples.
{%- endtrans %}</p>


<h3>{% trans %}Getting Started{% endtrans %}</h3>
<p>{% trans url='https://github.com/i2p/i2p.scripts/tree/master/plugin/makeplugin.sh' -%}
To create a plugin from an existing binary package you will need to get
makeplugin.sh from <a href="{{ url }}">the i2p.scripts repository in git</a>.
{%- endtrans %}</p>


<h3>{% trans %}Known Issues{% endtrans %}</h3>
<p>{% trans -%}
Note that the router's plugin architecture does <b>NOT</b> currently
provide any additional security isolation or sandboxing of plugins.
{%- endtrans %}</p>

<ul>
<li>{% trans -%}
Updates of a plugin with included jars (not wars) won't be recognized if
the plugin was already run, as it requires class loader trickery to flush the
class cache; a full router restart is required.
{%- endtrans %}</li>

<li>{% trans -%}
The stop button may be displayed even if there is nothing to stop.
{%- endtrans %}</li>

<li>{% trans -%}
Plugins running in a separate JVM create a <code>logs/</code> directory in
<code>$CWD</code>.
{%- endtrans %}</li>

<li>{% trans -%}
No initial keys are present, except for those of jrandom and zzz (using the
same keys as for router update), so the first key seen for a signer is
automatically accepted&mdash;there is no signing key authority.
{%- endtrans %}</li>

<li>{% trans -%}
When deleting a plugin, the directory is not always deleted, especially on
Windows.
{%- endtrans %}</li>

<li>{% trans -%}
Installing a plugin requiring Java 1.6 on a Java 1.5 machine will result in a
"plugin is corrupt" message if pack200 compression of the plugin file is used.
{%- endtrans %}</li>

<li>{% trans -%}
Theme and translation plugins are untested.
{%- endtrans %}</li>

<li>{% trans -%}
Disabling autostart doesn't always work.
{%- endtrans %}</li>
</ul>

<!-- vim: set noai ff=unix nosi ft=html tw=79 et sw=4 ts=4 spell spelllang=en: -->
{% endblock %}