i2p.www/www.i2p2/pages/updates.html

{% extends "_layout.html" %}
{% block title %}I2P Software Update Specification{% endblock %}
{% block content %}
Page last updated August 2010, current as of router version 0.8.
<h3>Overview</h3>
<p> 
I2P uses a simple, yet secure, system for automated software update.
The router console periodically pulls a news file from a configurable I2P URL.
There is a hardcoded backup URL pointing to the project website, in case
the default project news host goes down.
</p><p>
The contents of the news file are displayed on the home page of the router console.
In addition, the news file contains the most recent version number of the software.
If the version is higher than the router's version number, it will
display an indication to the user that an update is available.
</p><p>
The router may optionally download, or download and install, the new version
if configured to do so.
</p>

<h3>News File Specification</h3>
<p>
The news.xml file may contain the following elements:
</p>
<pre>
&lt;i2p.news date="$Date: 2010-01-22 00:00:00 $" /&gt;
&lt;i2p.release version="0.7.14" date="2010/01/22" minVersion="0.6" /&gt;
</pre>

<p>
The elements may be included inside XML comments to prevent interpretation by browsers.
The i2p.release element and version are required. All others are optional and are
currently unused.
</p><p>
The news source is trusted only to indicate that a new version is available.
It does not specify the URL of the update, the checksum, or any other information.
</p>


<h3>Update File Specification</h3>
<p>
The signed update file, traditionally named i2pupdate.sud,
is simply a zip file with a prepended 56 byte header.
The header contains:
<ul>
<li>
A 40-byte <a href="common_structures_spec.html#type_signature">DSA signature</a>
</li><li>
A 16-byte plugin version in UTF-8, padded with trailing zeroes if necessary
</li></ul>
</p><p>
The signature covers only the zip archive - not the prepended version.
The signature must match one of the <a href="common_structures_spec.html#type_SigningPublicKey">DSA public keys</a> configured into the router,
which has a hardcoded default list of keys of the current project release managers.
</p><p>
For version comparison purposes, version fields contain [0-9]*, field separators are
'-', '_', and '.', and all other characters are ignored.
</p>

<h3>Download and Installation</h3>
<p>
The router downloads the update file from one in a configurable list of I2P URLs,
using the built-in HTTP client and proxy.
There are several hardcoded default URLs.
The router verifies that the update file version is newer before installation.
It also, of course, verifies the signature.
</p><p>
The zip file is extracted in the base $I2P installation directory.
</p><p>
Recent router versions support Pack200 decompression.
Files inside the zip archive with a .jar.pack or .war.pack suffix
are transparently decompressed to a .jar or .war file.
Update files containing .pack files are traditionally named with a '.su2' suffix.
Pack200 shrinks the update files by about 60%.
</p>


<h3>Future Work</h3>
<ul><li>
The router could check the update version with a HEAD before downloading.
This will eliminate the problem of one or more update hosts that cannot
be notified to host the new file at update time.
</li><li>
When a new update file specification is defined, it should use a larger
DSA signature, and the signature should cover the version.
A file format version number might be a good idea too.
</li><li>
The network will eventually grow too large for update over HTTP.
The built-in BitTorrent client, i2psnark, may be used as a distributed update method.
This development effort was started in 2009 but is on hold until it is required.
</li><li>
The router update mechanism is part of the web router console.
There is currently no provision for updates of an embedded router lacking the router console.
</li></ul>



{% endblock %}