207 lines
13 KiB
HTML
207 lines
13 KiB
HTML
{% extends "global/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 <a href="http://itoopie.net/">I2PControl</a>.
|
|
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>
|
|
<p>I2PControl is by default listening on localhost:7650</p>
|
|
|
|
<h2>API, version 1.</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 – Description
|
|
<ul>Request
|
|
<li>Param-key-1 – Description</li>
|
|
<li>Param-key-2 – Description</li>
|
|
<li>Token – Token used for authenticating every request (excluding the 'Authenticate' RPC method)</li>
|
|
</ul>
|
|
<ul>Response
|
|
<li>Result-key-1 – Description</li>
|
|
<li>Result-key-2 – Description</li>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h4>Implemented methods</h4>
|
|
<ul>Authenticate – Creates and returns an authentication token used for further communication.
|
|
<ul>Request
|
|
<li>API – [long] The version of the I2PControl API used by the client.</li>
|
|
<li>Password – [String] The password used for authenticating against the remote server.</li>
|
|
</ul>
|
|
<ul>Response
|
|
<li>API – [long] The primare I2PControl API version implemented by the server.</li>
|
|
<li>Token – [String] The token used for further communication.</li>
|
|
</ul>
|
|
</ul>
|
|
<ul>Echo – Echoes the value of the echo key, used for debugging and testing.
|
|
<ul>Request
|
|
<li>Echo – [String] Value will be returned in response.</li>
|
|
<li>Token – [String]Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
|
|
</ul>
|
|
<ul>Response
|
|
<li>Result – [String] Value of the key 'echo' in the request.</li>
|
|
</ul>
|
|
</ul>
|
|
<ul>GetRate – Fetches rateStat from router statManager. Creates stat if not already created.
|
|
<ul>Request
|
|
<li>Stat – [String] Determines which rateStat to fetch, see <a href="ratestats.html">ratestats</a>.</li>
|
|
<li>Period – [long] Determines which period a stat is fetched for. Measured in ms.</li>
|
|
<li>Token – [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
|
|
</ul>
|
|
<ul>Response
|
|
<li>Result – [double] Returns the average value for the reuested rateStat and period.</li>
|
|
</ul>
|
|
</ul>
|
|
<ul>I2PControl – Manages I2PControl. Ports, passwords and the like.
|
|
<ul>Request
|
|
<li>*i2pcontrol.address – [String] Sets a new listen address for I2PControl (only 127.0.0.1 and 0.0.0.0 are implemented in I2PControl currently).</li>
|
|
<li>*i2pcontrol.password – [String] Sets a new password for I2PControl, all Authentication tokens will be revoked.</li>
|
|
<li>*i2pcontrol.port – [String] Switches which port I2PControl will listen for connections on.</li>
|
|
<li>Token – [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
|
|
</ul>
|
|
<ul>Response
|
|
<li>**i2pcontrol.address – [null] Returned if address was changed</li>
|
|
<li>**i2pcontrol.password – [null] Returned if setting was changed</li>
|
|
<li>**i2pcontrol.port – [null] Returned if setting was changed</li>
|
|
<li>SettingsSaved – [Boolean] Returns true if any changes were made.</li>
|
|
<li>RestartNeeded – [Boolean] Returns true if any changes requiring a restart to take effect were made.</li>
|
|
</ul>
|
|
</ul>
|
|
<ul>RouterInfo – Fetches basic information about hte I2P router. Uptime, version etc.
|
|
<ul>Request
|
|
<li>*i2p.router.status – [n/a]</li>
|
|
<li>*i2p.router.uptime – [n/a]</li>
|
|
<li>*i2p.router.version – [n/a]</li>
|
|
<li>*i2p.router.net.bw.inbound.1s – [n/a] </li>
|
|
<li>*i2p.router.net.bw.inbound.15s – [n/a] </li>
|
|
<li>*i2p.router.net.bw.outbound.1s – [n/a] </li>
|
|
<li>*i2p.router.net.bw.outbound.15s – [n/a] </li>
|
|
<li>*i2p.router.net.status – [n/a]</li>
|
|
<li>*i2p.router.net.tunnels.participating – [n/a] </li>
|
|
<li>*i2p.router.netdb.activepeers – [n/a] </li>
|
|
<li>*i2p.router.netdb.fastpeers – [n/a] </li>
|
|
<li>*i2p.router.netdb.highcapacitypeers – [n/a] </li>
|
|
<li>*i2p.router.netdb.isreseeding – [n/a] </li>
|
|
<li>*i2p.router.netdb.knownpeers – [n/a] </li>
|
|
<li>Token – [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
|
|
</ul>
|
|
<ul>Response
|
|
<li>**i2p.router.status – [String] What the status of the router is.</li>
|
|
<li>**i2p.router.uptime – [long] What the uptime of the router is in ms.</li>
|
|
<li>**i2p.router.version – [String] What version of I2P the router is running.</li>
|
|
<li>**i2p.router.net.bw.inbound.1s – [double] The 1 second average inbound bandwidth in Bps.</li>
|
|
<li>**i2p.router.net.bw.inbound.15s – [double] The 15 second average inbound bandwidth in Bps.</li>
|
|
<li>**i2p.router.net.bw.outbound.1s – [double] The 1 second average outbound bandwidth in Bps.</li>
|
|
<li>**i2p.router.net.bw.outbound.15s – [double] The 15 second average outbound bandwidth in Bps.</li>
|
|
<li>**i2p.router.net.status – [long] What the current network status is. According to the below enum:
|
|
<ul>
|
|
<li>0 – OK</li>
|
|
<li>1 – TESTING</li>
|
|
<li>2 – FIREWALLED</li>
|
|
<li>3 – HIDDEN</li>
|
|
<li>4 – WARN_FIREWALLED_AND_FAST</li>
|
|
<li>5 – WARN_FIREWALLED_AND_FLOODFILL</li>
|
|
<li>6 – WARN_FIREWALLED_WITH_INBOUND_TCP</li>
|
|
<li>7 – WARN_FIREWALLED_WITH_UDP_DISABLED</li>
|
|
<li>8 – ERROR_I2CP</li>
|
|
<li>9 – ERROR_CLOCK_SKEW</li>
|
|
<li>10 – ERROR_PRIVATE_TCP_ADDRESS</li>
|
|
<li>11 – ERROR_SYMMETRIC_NAT</li>
|
|
<li>12 – ERROR_UDP_PORT_IN_USE</li>
|
|
<li>13 – ERROR_NO_ACTIVE_PEERS_CHECK_CONNECTION_AND_FIREWALL</li>
|
|
<li>14 – ERROR_UDP_DISABLED_AND_TCP_UNSET</li>
|
|
</ul>
|
|
</li>
|
|
<li>**i2p.router.net.tunnels.participating – [long] How many tunnels on the I2P net are we participating in.</li>
|
|
<li>**i2p.router.netdb.activepeers – [long] How many peers have we communicated with recently.</li>
|
|
<li>**i2p.router.netdb.fastpeers &ndasg; [long] How many peers are considered 'fast'.</li>
|
|
<li>**i2p.router.netdb.highcapacitypeers – [long] How many peers are considered 'high capacity'.</li>
|
|
<li>**i2p.router.netdb.isreseeding – [boolean] Is the router reseeding hosts to its NetDB?</li>
|
|
<li>**i2p.router.netdb.knownpeers – [long] How many peers are known to us (listed in our NetDB).</li>
|
|
</ul>
|
|
</ul>
|
|
<ul>RouterManager – Manages I2P router restart/shutdown.
|
|
<ul>Request
|
|
<li>*Reseed – [n/a] Initiates a router reseed, fetching peers into our NetDB from a remote host.</li>
|
|
<li>*Restart – [n/a] Restarts the router.</li>
|
|
<li>*RestartGraceful – [n/a] Restarts the router gracefully (waits for participating tunnels to expire).</li>
|
|
<li>*Shutdown – [n/a] Shuts down the router.</li>
|
|
<li>*ShutdownGraceful – [n/a] Shuts down the router gracefully (waits for participating tunnels to expire).</li>
|
|
<li>Token – [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.</li>
|
|
</ul>
|
|
<ul>Response
|
|
<li>**Reseed – [null] If requested, verifies that a reseed has been initiated.</li>
|
|
<li>**Restart – [null] If requested, verifies that a restart has been initiated.</li>
|
|
<li>**RestartGraceful – [null] If requested, verifies that a graceful restart has been initiated.</li>
|
|
<li>**Shutdown – [null] If requested, verifies that a shutdown has been initiated</li>
|
|
<li>**ShutdownGraceful – [null] If requested, verifies that a graceful shutdown has been initiated</li>
|
|
</ul>
|
|
</ul>
|
|
<ul>NetworkSetting – Fetches or sets various network related settings. Ports, addresses etc.
|
|
<ul>Request
|
|
<li>*i2p.router.net.ntcp.port – [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 – [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 – [String] Use automatically detected ip for TCP transport. If null is submitted, current setting will be returned.</li>
|
|
<li>*i2p.router.net.ssu.port – [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 – [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 – [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 – [null] What ip has been detected by the UDP transport.</li>
|
|
<li>*i2p.router.net.upnp – [String] Is UPNP enabled. If null is submitted, current setting will be returned.</li>
|
|
<li>*i2p.router.net.bw.share – [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 – [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 – [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 – [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 – [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 – [String] If requested, returns the port used for the TCP transport.</li>
|
|
<li>**i2p.router.net.ntcp.hostname – [String] If requested, returns the hostname used for the TCP transport.</li>
|
|
<li>**i2p.router.net.ntcp.autoip – [String] If requested, returns the method used for automatically detecting ip for the TCP transport.</li>
|
|
<li>**i2p.router.net.ssu.port – [String] If requested, returns the port used for the UDP transport.</li>
|
|
<li>**i2p.router.net.ssu.hostname – [String] If requested, returns the hostname used for the UDP transport.</li>
|
|
<li>**i2p.router.net.ssu.autoip – [String] If requested, returns methods used for detecting the ip address of the UDP transport.</li>
|
|
<li>**i2p.router.net.ssu.detectedip – [String] If requested, returns what ip has been detected by the UDP transport.</li>
|
|
<li>**i2p.router.net.upnp – [String] If requested, returns the UPNP setting.</li>
|
|
<li>**i2p.router.net.bw.share – [String] If requested, returns how many percent of bandwidth is usable for participating tunnels.</li>
|
|
<li>**i2p.router.net.bw.in – [String] If requested, returns how many KB/s of inbound bandwidth is allowed.</li>
|
|
<li>**i2p.router.net.bw.out – [String] If requested, returns how many KB/s of outbound bandwidth is allowed.</li>
|
|
<li>**i2p.router.net.laptopmode – [String] If requested, returns the laptop mode.</li>
|
|
<li>SettingsSaved – [boolean] Have the provided settings been saved.</li>
|
|
<li>RestartNeeded – [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>
|
|
|
|
<h3>Error codes</h3>
|
|
<ul>Standard JSON-RPC2 error codes.
|
|
<li>-32700 – JSON parse error.</li>
|
|
<li>-32600 – Invalid request.</li>
|
|
<li>-32601 – Method not found.</li>
|
|
<li>-32603 – Internal error.</li>
|
|
</ul>
|
|
<ul>I2PControl specific error codes.
|
|
<li>-32001 – Invalid password provided.</li>
|
|
<li>-32002 – No authentication token presented.</li>
|
|
<li>-32003 – Authentication token doesn't exist.</li>
|
|
<li>-32004 – The provided authentication token was expired and will be removed.</li>
|
|
<li>-32005 – The version of the I2PControl API used wasn't specified, but is required to be specified.</li>
|
|
<li>-32006 – The version of the I2PControl API specified is not supported by I2PControl.</li>
|
|
</ul>
|
|
|
|
|
|
|
|
{% endblock %}
|