2011-06-27 11:26:59 +00:00
{% extends "_layout.html" %}
2011-07-12 16:51:08 +00:00
{% block title %}I2PControl API{% endblock %}
2011-06-27 11:26:59 +00:00
{% 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 >
2011-07-22 13:48:18 +00:00
< h2 > API, version 1.< / h2 >
2011-06-27 11:26:59 +00:00
< p >
Parameters are only provided in a named way (maps).
< h4 > JSON-RPC 2 format< / h4 >
2011-07-05 12:56:15 +00:00
< div class = "box" style = "clear: none;" > < pre >
2011-06-27 11:26:59 +00:00
Request:
2011-07-08 09:40:32 +00:00
{"id":"id", "method":"Method-name","params":{"Param-key-1":"param-value-1", "Param-key-2":"param-value-2", "Token":"**actual token**"}, "jsonrpc":"2.0"}
2011-06-27 11:26:59 +00:00
Response:
2011-07-08 09:40:32 +00:00
{"id":"id","result":{"Result-key-1":"result-value-1","Result-key-2":"result-value-2"},"jsonrpc":"2.0"}
2011-06-27 11:26:59 +00:00
< / pre > < / div >
< / p >
< ul > method-name – Description
< ul > Request
2011-07-08 09:40:32 +00:00
< 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 >
2011-06-27 11:26:59 +00:00
< / ul >
< ul > Response
2011-07-08 09:40:32 +00:00
< li > Result-key-1 – Description< / li >
< li > Result-key-2 – Description< / li >
2011-06-27 11:26:59 +00:00
< / ul >
< / ul >
< h4 > Implemented methods< / h4 >
2011-07-08 09:40:32 +00:00
< ul > Authenticate – Creates and returns an authentication token used for further communication.
2011-07-05 12:56:15 +00:00
< ul > Request
2011-07-22 13:48:18 +00:00
< li > API – [long] The version of the I2PControl API used by the client.< / li >
2011-07-08 09:40:32 +00:00
< li > Password – [String] The password used for authenticating against the remote server.< / li >
2011-07-05 12:56:15 +00:00
< / ul >
< ul > Response
2011-07-22 13:48:18 +00:00
< li > API – [long] The primare I2PControl API version implemented by the server.< / li >
2011-07-08 09:40:32 +00:00
< li > Token – [String] The token used for further communication.< / li >
2011-07-05 12:56:15 +00:00
< / ul >
< / ul >
2011-07-08 09:40:32 +00:00
< ul > Echo – Echoes the value of the echo key, used for debugging and testing.
2011-06-27 11:26:59 +00:00
< ul > Request
2011-07-08 09:40:32 +00:00
< 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 >
2011-06-27 11:26:59 +00:00
< / ul >
< ul > Response
2011-07-08 09:40:32 +00:00
< li > Result – [String] Value of the key 'echo' in the request.< / li >
2011-06-27 11:26:59 +00:00
< / ul >
< / ul >
2011-07-08 09:40:32 +00:00
< ul > GetRate – Fetches rateStat from router statManager. Creates stat if not already created.
2011-06-27 11:26:59 +00:00
< ul > Request
2011-07-08 09:40:32 +00:00
< li > Stat – [String] Determines which rateStat to fetch, see < a href = "ratestats.html" > ratestats< / a > .< / li >
2011-07-19 14:09:16 +00:00
< li > Period – [long] Determines which period a stat is fetched for.< / li >
2011-07-08 09:40:32 +00:00
< li > Token – [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.< / li >
2011-06-27 11:26:59 +00:00
< / ul >
< ul > Response
2011-07-08 09:40:32 +00:00
< li > Result – [double] Returns the average value for the reuested rateStat and period.< / li >
2011-06-27 11:26:59 +00:00
< / ul >
< / ul >
2011-07-19 14:09:16 +00:00
< ul > I2PControl – Manages I2PControl. Ports, passwords and the like.
< ul > Request
< 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.password – [null] Returned if setting was changed< / li >
< li > **i2pcontrol.port – [null] Returned if setting was changed< / li >
< / ul >
< / ul >
2011-07-15 12:42:44 +00:00
< 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 >
2011-07-22 13:48:18 +00:00
< 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 >
2011-07-19 14:09:16 +00:00
< li > *i2p.router.net.status – [n/a]< / li >
2011-07-22 13:48:18 +00:00
< li > *i2p.router.net.tunnels.participating – [n/a] < / li >
2011-07-26 11:58:30 +00:00
< li > *i2p.router.netdb.activepeers – [n/a] < / li >
< li > *i2p.router.netdb.fastpeers &ndasg; [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 >
2011-07-19 14:09:16 +00:00
< li > Token – [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.< / li >
2011-07-15 12:42:44 +00:00
< / ul >
< ul > Response
< li > **i2p.router.status – [String] What the status of the router is.< / li >
2011-07-26 13:19:40 +00:00
< li > **i2p.router.uptime – [long] What the uptime of the router is in ms.< / li >
2011-07-26 12:41:51 +00:00
< li > **i2p.router.version – [String] What version of I2P the router is running.< / li >
2011-07-22 13:48:18 +00:00
< 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 >
2011-07-15 12:42:44 +00:00
< li > **i2p.router.net.status – [String] What the current netowrk status is.< / li >
2011-07-22 13:48:18 +00:00
< li > **i2p.router.net.tunnels.participating – [long] How many tunnels on the I2P net are we participating in.< / li >
2011-07-26 11:58:30 +00:00
< 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 >
2011-07-15 12:42:44 +00:00
< / ul >
< / ul >
2011-07-26 11:58:30 +00:00
< ul > RouterManager – Manages I2P router restart/shutdown.
2011-07-15 12:42:44 +00:00
< ul > Request
2011-07-26 11:58:30 +00:00
< li > *Reseed – [n/a] Initiates a router reseed, fetching peers into our NetDB from a remote host.< / li >
2011-07-15 12:42:44 +00:00
< 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 >
2011-07-19 14:09:16 +00:00
< li > Token – [String] Token used for authenticating the client. Is provided by the server via the 'Authenticate' RPC method.< / li >
2011-07-15 12:42:44 +00:00
< / ul >
< ul > Response
2011-07-26 11:58:30 +00:00
< li > **Reseed – [null] If requested, verifies that a reseed has been initiated.< / li >
2011-07-15 12:42:44 +00:00
< 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.
2011-07-07 14:50:46 +00:00
< ul > Request
2011-07-08 09:40:32 +00:00
< 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 >
2011-07-07 14:50:46 +00:00
< / ul >
< ul > Response
2011-07-08 09:40:32 +00:00
< 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 >
2011-07-08 09:57:11 +00:00
< 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 >
2011-07-07 14:50:46 +00:00
< / ul >
< / ul >
< p > * denotes an optional value.< / p >
2011-07-08 09:40:32 +00:00
< p > ** denotes a possibly occuring return value< / p >
2011-07-07 14:50:46 +00:00
2011-07-21 14:05:41 +00:00
< 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 >
2011-07-26 12:03:26 +00:00
< 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 >
2011-07-21 14:05:41 +00:00
< / ul >
2011-07-07 14:50:46 +00:00
2011-06-27 11:26:59 +00:00
{% endblock %}
