i2p.www/i2p2www/pages/site/docs/spec/configuration.html

{% extends "global/layout.html" %}
{% block title %}{% trans %}Configuration File Specification{% endtrans %}{% endblock %}
{% block lastupdated %}{% trans %}January 2014{% endtrans %}{% endblock %}
{% block accuratefor %}0.9.9{% endblock %}
{% block content %}
<h2>{% trans %}Overview{% endtrans %}</h2>
<p>{% trans -%}
This page provides a general specification of I2P configuration files,
used by the router and various applications.
It also gives an overview of the information contained in the various files,
and links to detailed documentation where available.
{%- endtrans %}</p>


<h2>{% trans %}General Format{% endtrans %}</h2>
<p>{% trans url='http://docs.oracle.com/javase/1.5.0/docs/api/java/util/Properties.html#load%28java.io.InputStream%29' -%}
An I2P configuration file is formatted as specified in
<a href="{{ url }}">Java Properties</a>
with the following exceptions:
{%- endtrans %}</p>
<ul>
<li>{% trans %}Encoding must be UTF-8{% endtrans %}</li>
<li>{% trans %}Does not use or recognize any escapes, including '\', so lines may not be continued{% endtrans %}</li>
<li>{% trans %}'#' or ';' starts a comment, but '!' does not{% endtrans %}</li>
<li>{% trans %}'#' starts a comment in any position but ';' must be in column 1 to start a comment{% endtrans %}</li>
<li>{% trans %}Leading and trailing whitespace is not trimmed on keys{% endtrans %}</li>
<li>{% trans %}Leading and trailing whitespace is trimmed on values{% endtrans %}</li>
<li>{% trans %}'=' is the only key-termination character (not ':' or whitespace){% endtrans %}</li>
<li>{% trans %}Lines without '=' are ignored. It does not store the key with a value of ""{% endtrans %}</li>
<li>{% trans %}As there are no escapes, keys may not contain '#', '=', or '\n', or start with ';'{% endtrans %}</li>
<li>{% trans %}As there are no escapes, values may not contain '#' or '\n', or start or end with '\r' or whitespace{% endtrans %}</li>
</ul>

<p>{% trans -%}
The file need not be sorted, but most applications do sort by key when
writing to the file, for ease of reading and manual editing.
{%- endtrans %}</p>

<p>{% trans url='http://docs.i2p-projekt.de/javadoc/net/i2p/data/DataHelper.html',
commonstructures=site_url('docs/spec/common-structures') -%}
Reads and writes are implemented in
<a href="{{ url }}">DataHelper loadProps() and storeProps()</a>.
Note that the file format is significantly different than the
serialized format for I2P protocols specified in
<a href="{{ commonstructures }}#type_Mapping">Mapping</a>.
{%- endtrans %}</p>

<h2>{% trans %}Core library and router{% endtrans %}</h2>

<h3>{% trans %}Clients{% endtrans %} (clients.config)</h3>
<p>{% trans -%}
Configured via /configclients in the router console.
{%- endtrans %}</p>
<p>
The format is as follows:
</p><p>
Lines are of the form clientApp.x.prop=val, where x is the app number.
App numbers MUST start with 0 and be consecutive.
</p><p>
Properties are as follows:
<pre>
	main: Full class name. Required. The constructor or main() method in this
	      class will be run, depending on whether the client is managed or unmanaged.
              See below for details.
	name: Name to be displayed on console.
	args: Arguments to the main class, separated by spaces or tabs.
	      Arguments containing spaces or tabs may be quoted with ' or "
	delay: Seconds before starting, default 120
	onBoot: {true|false}, default false, forces a delay of 0,
	        overrides delay setting
	startOnLoad: {true|false} Is the client to be run at all?
	                   Default true
</pre>
</p><p>
The following additional properties are used only by plugins:
<pre>
	stopargs: Arguments to stop the client.
	uninstallargs: Arguments to uninstall the client.
	classpath: Additional classpath elements for the client,
	           separated by commas.
</pre>
</p><p>
The following substitutions are made in the args, stopargs,
uninstallargs, and classpath lines, for plugins only:
<pre>
	$I2P: The base I2P install directory
	$CONFIG: The user's configuration directory (e.g. ~/.i2p)
	$PLUGIN: This plugin's directory (e.g. ~/.i2p/plugins/foo)
</pre>
</p><p>
All properties except "main" are optional.
Lines starting with "#" are comments.
</p><p>
If the delay is less than zero, the client is run immediately,
in the same thread, so that exceptions may be propagated to the console.
In this case, the client should either throw an exception, return quickly,
or spawn its own thread.
If the delay is greater than or equal to zero, it will be run
in a new thread, and exceptions will be logged but not propagated
to the console.
</p>
<p>
Clients may be "managed" or "unmanaged".
</p>

<h4>Managed Clients</h4>
<p>
As of release 0.9.4, the router supports "managed" clients.
Managed clients are instantiated and started by the <code>ClientAppManager</code>.
The ClientAppManager maintains a reference to the client and receives updates on the client's state.
Managed clients are preferred, as it is much easier to implement state tracking
and to start and stop a client. It also is much easier to avoid static references in the client code
which could lead to excessive memory usage after a client is stopped.
</p>
<p>
Managed clients implement either the <code>net.i2p.app.ClientApp</code> or
<code>net.i2p.router.app.RouterApp</code> interface.
Clients implementing the ClientApp interface MUST provide the following constructor:
<pre>
    public MyClientApp(I2PAppContext context, ClientAppManager listener, String[] args)
</pre>
Clients implementing the RouterApp interface MUST provide the following constructor:
<pre>
    public MyClientApp(RouterContext context, ClientAppManager listener, String[] args)
</pre>
The args will be the arguments specified in the clients.config file.
</p>

<h4>Unmanaged Clients</h4>
<p>
If the main class does not implement a managed interface,
it will be started with main() with the arguments specified,
and stopped with main() with the arguments specified.
</p>

<h3>{% trans %}Logger{% endtrans %} (logger.config)</h3>
<p>{% trans -%}
Configured via /configlogging in the router console.
{%- endtrans %}</p>
<p>
Properties are as follows:
<pre>
    logger.format={dctpm}*
        where d = date, c = class, t = thread name, p = priority, m = message
    logger.dateFormat=HH:mm:ss.SSS
    logger.logFileName=name
    logger.logFileSize=nnn[K|M|G]
    logger.logRotationLimit=n
    logger.displayOnScreen=true|false
    logger.consoleBufferSize=n
    logger.minimumOnScreenLevel=CRIT|ERROR|WARN|INFO|DEBUG
    logger.defaultLevel=CRIT|ERROR|WARN|INFO|DEBUG
    logger.logBufferSize=n
    logger.dropOnOverflow=true|false
    logger.dropDuplicates=true|false
    logger.record.{class}=CRIT|ERROR|WARN|INFO|DEBUG
</pre>
</p>

<h3>{% trans %}Individual Plugin{% endtrans %} (xxx/plugin.config)</h3>
<p>{% trans pluginspec=site_url('docs/spec/plugin') -%}
See <a href="{{ pluginspec }}">the plugin specification</a>.
{%- endtrans %}</p>

<h3>{% trans %}Plugins{% endtrans %} (plugins.config)</h3>
<p>{% trans -%}
Enable/disable for each installed plugin.
{%- endtrans %}</p>

<h3>{% trans %}Router{% endtrans %} (router.config)</h3>
<p>{% trans -%}
Configured via /configadvanced in the router console.
{%- endtrans %}</p>

<h2>{% trans %}Applications{% endtrans %}</h2>

<h3>{% trans %}Addressbook{% endtrans %} (addressbook/config.txt)</h3>
<p>{% trans -%}
See documentation in SusiDNS.
{%- endtrans %}</p>

<h3>I2PSnark (i2psnark.config)</h3>
<p>{% trans -%}
Configured via the application gui.
{%- endtrans %}</p>

<h3>I2PTunnel (i2ptunnel.config)</h3>
<p>{% trans -%}
Configured via the /i2ptunnel application in the router console.
{%- endtrans %}</p>

<h3>{% trans %}Router Console{% endtrans %}</h3>
<p>{% trans -%}
The router console uses the router.config file.
{%- endtrans %}</p>

<h3>SusiMail (susimail.config)</h3>
<p>{% trans -%}
See post on zzz.i2p.
{%- endtrans %}</p>
<!--
<h3>Systray (systray.config)</h3>
<p>
TBD
</p>
-->
{% endblock %}