i2p.www/www.i2p2/pages/i2pcontrol.html

{% extends "_layout.html" %}
{% block title %}I2PControl API{% endblock %}
{% block content %}
<h1>I2PControl - Remote Control Service</h1>
<p>I2P enables a <a href="http://en.wikipedia.org/wiki/JSON-RPC">JSONRPC2</a> interface via the plugin I2PControl. 
The aim of the interface is to provide simple way to interface with a running I2P node. A client, itoopie, has been developed in parallel.
The JSONRPC2 implementation for the client as well as the plugin is provided by the java libraries <a href="http://software.dzhuvinov.com/json-rpc-2.0.html">JSON-RPC 2.0</a>.  
A list of implementations of JSON-RPC for various languages can be found at <a href="http://json-rpc.org/wiki/implementations">the JSON-RPC wiki</a>.
</p>

<h2>API</h2>
<p>
Parameters are only provided in a named way (maps).

<h4>JSON-RPC 2 format</h4>
<div class="box" style="clear: none;"><pre>
Request:
{"id":"id", "method":"Method-name","params":{"Param-key-1":"param-value-1", "Param-key-2":"param-value-2", "Token":"**actual token**"}, "jsonrpc":"2.0"}
Response:
{"id":"id","result":{"Result-key-1":"result-value-1","Result-key-2":"result-value-2"},"jsonrpc":"2.0"}

</pre></div>
</p>
<ul>method-name &ndash; Description
	<ul>Request
		<li>Param-key-1 &ndash; Description</li>
		<li>Param-key-2 &ndash; Description</li>
		<li>Token &ndash; Token used for authenticating every request (excluding the 'Authenticate' RPC method)</li>
	</ul>
	<ul>Response
		<li>Result-key-1 &ndash; Description</li>
		<li>Result-key-2 &ndash; Description</li>
	</ul>
</ul>

<h4>Implemented methods</h4>
<ul>Authenticate &ndash; Creates and returns an authentication token used for further communication.
	<ul>Request
		<li>Password &ndash; [String] The password used for authenticating against the remote server.</li>
	</ul>
	<ul>Response
		<li>Token &ndash; [String] The token used for further communication.</li>
	</ul>
</ul>
<ul>Echo &ndash; Echoes the value of the echo key, used for debugging and testing.
	<ul>Request
		<li>Echo &ndash; [String] Value will be returned in response.</li>
		<li>Token &ndash; [String]Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
	</ul>
	<ul>Response
		<li>Result &ndash; [String] Value of the key 'echo' in the request.</li>
	</ul>
</ul>
<ul>GetRate &ndash; Fetches rateStat from router statManager. Creates stat if not already created.
	<ul>Request
		<li>Stat &ndash; [String] Determines which rateStat to fetch, see <a href="ratestats.html">ratestats</a>.</li>
		<li>Period &ndash; [double] Determines which period a stat is fetched for.</li>
		<li>Token &ndash; [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
	</ul>
	<ul>Response
		<li>Result &ndash; [double] Returns the average value for the reuested rateStat and period.</li>
	</ul>
</ul>
<ul>RouterInfo &ndash; Fetches basic information about hte I2P router. Uptime, version etc.
	<ul>Request
		<li>*i2p.router.status &ndash; [n/a]</li>
		<li>*i2p.router.uptime &ndash; [n/a]</li>
		<li>*i2p.router.version	&ndash; [n/a]</li>
		<li>*i2p.router.net.status &ndash; [n/a]</li>	
	</ul>
	<ul>Response
		<li>**i2p.router.status &ndash; [String] What the status of the router is.</li>
		<li>**i2p.router.uptime &ndash; [String] What the uptime of the router is.</li>
		<li>**i2p.router.version	&ndash; [String] What version of I2P the router is running.</li>
		<li>**i2p.router.net.status &ndash; [String] What the current netowrk status is.</li>
	</ul>
</ul>
<ul>RouterRunner &ndash; Manages I2P router restart/shutdown.
	<ul>Request
		<li>*Restart &ndash; [n/a] Restarts the router.</li>
		<li>*RestartGraceful &ndash; [n/a] Restarts the router gracefully (waits for participating tunnels to expire).</li>
		<li>*Shutdown &ndash; [n/a] Shuts down the router.</li>
		<li>*ShutdownGraceful &ndash; [n/a] Shuts down the router gracefully (waits for participating tunnels to expire).</li>
	</ul>
	<ul>Response
		<li>**Restart &ndash; [null] If requested, verifies that a restart has been initiated.</li>
		<li>**RestartGraceful &ndash; [null] If requested, verifies that a graceful restart has been initiated.</li>
		<li>**Shutdown &ndash; [null] If requested, verifies that a shutdown has been initiated</li>
		<li>**ShutdownGraceful &ndash; [null] If requested, verifies that a graceful shutdown has been initiated</li>
	</ul>
</ul>
<ul>NetworkSetting &ndash; Fetches or sets various network related settings. Ports, addresses etc.
	<ul>Request
		<li>*i2p.router.net.ntcp.port &ndash; [String] What port is used for the TCP transport. If null is submitted, current setting will be returned.</li>
		<li>*i2p.router.net.ntcp.hostname &ndash; [String] What hostname is used for the TCP transport. If null is submitted, current setting will be returned.</li>
		<li>*i2p.router.net.ntcp.autoip &ndash; [String] Use automatically detected ip for TCP transport. If null is submitted, current setting will be returned.</li>
		<li>*i2p.router.net.ssu.port &ndash; [String] What port is used for the UDP transport. If null is submitted, current setting will be returned.</li>
		<li>*i2p.router.net.ssu.hostname &ndash; [String] What hostname is used for the UDP transport. If null is submitted, current setting will be returned.</li>
		<li>*i2p.router.net.ssu.autoip &ndash; [String] Which methods should be used for detecting the ip address of the UDP transport. If null is submitted, current setting will be returned.</li>
		<li>*i2p.router.net.ssu.detectedip &ndash; [null] What ip has been detected by the UDP transport.</li>
		<li>*i2p.router.net.upnp &ndash; [String] Is UPNP enabled. If null is submitted, current setting will be returned.</li>
		<li>*i2p.router.net.bw.share &ndash; [String] How many percent of bandwidth is usable for participating tunnels. If null is submitted, current setting will be returned.</li>
		<li>*i2p.router.net.bw.in &ndash; [String] How many KB/s of inbound bandwidth is allowed. If null is submitted, current setting will be returned.</li>
		<li>*i2p.router.net.bw.out &ndash; [String] How many KB/s of outbound bandwidth is allowed. If null is submitted, current setting will be returned.</li>
		<li>*i2p.router.net.laptopmode &ndash; [String] Is laptop mode enabled (change router identity and UDP port when IP changes ). If null is submitted, current setting will be returned.</li>
		<li>Token &ndash; [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method. If null is submitted, current setting will be returned.</li>
	</ul>
	<ul>Response
		<li>**i2p.router.net.ntcp.port &ndash; [String] If requested, returns the port used for the TCP transport.</li>
		<li>**i2p.router.net.ntcp.hostname &ndash; [String] If requested, returns the hostname used for the TCP transport.</li>
		<li>**i2p.router.net.ntcp.autoip &ndash; [String] If requested, returns the method used for automatically detecting ip for the TCP transport.</li>
		<li>**i2p.router.net.ssu.port &ndash; [String] If requested, returns the port used for the UDP transport.</li>
		<li>**i2p.router.net.ssu.hostname &ndash; [String] If requested, returns the hostname used for the UDP transport.</li>
		<li>**i2p.router.net.ssu.autoip &ndash; [String] If requested, returns methods used for detecting the ip address of the UDP transport.</li>
		<li>**i2p.router.net.ssu.detectedip &ndash; [String] If requested, returns what ip has been detected by the UDP transport.</li>
		<li>**i2p.router.net.upnp &ndash; [String] If requested, returns the UPNP setting.</li>
		<li>**i2p.router.net.bw.share &ndash; [String] If requested, returns how many percent of bandwidth is usable for participating tunnels.</li>
		<li>**i2p.router.net.bw.in &ndash; [String] If requested, returns how many KB/s of inbound bandwidth is allowed.</li>
		<li>**i2p.router.net.bw.out &ndash; [String] If requested, returns how many KB/s of outbound bandwidth is allowed.</li>
		<li>**i2p.router.net.laptopmode &ndash; [String] If requested, returns the laptop mode.</li>
		<li>SettingsSaved &ndash; [boolean] Have the provided settings been saved.</li>
		<li>RestartNeeded &ndash; [boolean] Is a restart needed for the new settings to be used.</li>
	</ul>
</ul>
<p>* denotes an optional value.</p>
<p>** denotes a possibly occuring return value</p>



{% endblock %}