==================== i2pcontrol-expansion ==================== .. meta:: :author: Nick2k4 :created: 2026-05-20 :lastupdated: 2026-05-20 :status: Open .. contents:: Overview ======== This proposal exposes new information to the i2pcontrol API, allowing for greater flexibility. This information includes: adding, deleting, retrieving, and modifying addressbooks, and hidden services. This proposal also exposes more information about your router, such as, peers, news, netdb, and more. Motivation ========== The reason for this proposal is to allow for greater flexibility in the I2P API for applications to implement and manage an I2P administrative interface. Exposing such information to i2pcontrol allows for users to create more advanced applications and provide better support for remote management. Design ====== When users interact with the i2pcontrol API, they will be able to access new endpoints that provide the information mentioned above. For example, the i2pcontrol API will expose new methods `TunnelManager` and `AddressBook` that will allow users to enter parameters to create, delete, retrieve, and modify tunnels and addressbooks. Additionally, the pre-existing `RouterInfo` method will have new parameters to expose information about the router. Security implications ===================== There are no expected additional security implications from this proposal, as the information being exposed is already accessible through other means. However, it is important to ensure that proper authentication and authorization mechanisms are in place for accessing the i2pcontrol API, to prevent unauthorized access to sensitive information or control over the router. API Specification & Methods =========================== All requests follow the JSON-RPC 2.0 structure: ```json { "jsonrpc": "2.0", "method": "MethodName", "params": { // method-specific parameters }, "id": 1 } ``` Method - RouterInfo ------------------- Below contains the new parameters for `RouterInfo` method and what they return: - `i2p.router.news` - returns all router news entries. - `i2p.router.id` - returns the router hash as a Base64 string, or `null`. - `i2p.router.clockskew` - returns the average peer clock skew, or `null`. - `i2p.router.info` - returns the serialized RouterInfo as a Base64 string, or `null`. - `i2p.router.logs` - returns recent router log messages. - `i2p.router.logs.clear` - clears the router log buffer and returns `"success"`. - `i2p.router.net.total.received.bytes` - returns total bytes received since startup. *(adopted from i2pd)* - `i2p.router.net.total.sent.bytes` - returns total bytes sent since startup. *(adopted from i2pd)* - `i2p.router.net.total.transit.bytes` - returns total transit bytes forwarded since startup. *(adopted from i2pd)* - `i2p.router.net.bw.transit.15s` - returns 15-second average transit bandwidth (bytes/sec). *(adopted from i2pd)* - `i2p.router.net.tunnels.shareratio` - returns the tunnel share ratio. - `i2p.router.net.tunnels.participating.info` - returns participating tunnel info. - `i2p.router.net.tunnels.i2ptunnel` - returns configured I2PTunnel controller info (quick stats of all). - `i2p.router.net.tunnels.exploratory.inbound` - returns exploratory inbound tunnel count. - `i2p.router.net.tunnels.exploratory.outbound` - returns exploratory outbound tunnel count. - `i2p.router.net.tunnels.exploratory.info.list` - returns exploratory tunnel info list. - `i2p.router.net.tunnels.client.inbound` - returns client inbound tunnel count. - `i2p.router.net.tunnels.client.outbound` - returns client outbound tunnel count. - `i2p.router.net.tunnels.client.info.list` - returns client tunnel info list. - `i2p.router.net.status.v6` - returns IPv6 network status code. *(adopted from i2pd)* - `i2p.router.net.error` - returns IPv4 network error code. *(adopted from i2pd)* - `i2p.router.net.error.v6` - returns IPv6 network error code. *(adopted from i2pd)* - `i2p.router.net.testing` - returns whether IPv4 network is in testing state (0 or 1). *(adopted from i2pd)* - `i2p.router.net.testing.v6` - returns whether IPv6 network is in testing state (0 or 1). *(adopted from i2pd)* - `i2p.router.net.tunnels.successrate` - returns recent tunnel build success rate (%). *(adopted from i2pd)* - `i2p.router.net.tunnels.totalsuccessrate` - returns total tunnel build success rate since startup (%). *(adopted from i2pd)* - `i2p.router.net.tunnels.queue` - returns tunnel build request queue size. *(adopted from i2pd)* - `i2p.router.net.tunnels.tbmqueue` - returns Tunnel Build Message queue size. *(adopted from i2pd)* - `i2p.router.netdb.peers` - returns a list of known peer hashes. - `i2p.router.netdb.activepeers.info` - returns serialized RouterInfo data for active peers. - `i2p.router.netdb.ntcp.limit` - returns NTCP connection limit. - `i2p.router.netdb.ssu.limit` - returns SSU connection limit. - `i2p.router.netdb.bannedpeers` - returns banned peers with ban details. - `i2p.router.netdb.activepeers.list` - returns active peer hashes. - `i2p.router.netdb.peers.list` - returns known peer hashes. - `i2p.router.netdb.peers.info` - returns serialized RouterInfo data for known peers. - `i2p.router.netdb.activepeers.stats` - returns active peer stats. - `i2p.router.addressbook.private.list` - returns private address book entries. - `i2p.router.addressbook.local.list` - returns local address book entries. - `i2p.router.addressbook.router.list` - returns router address book entries. - `i2p.router.addressbook.published.list` - returns published address book entries. - `i2p.router.addressbook.subscriptions` - returns subscription file path and entries. - `i2p.router.addressbook.config` - returns address book config path and entries. Example: ```json { "jsonrpc": "2.0", "method": "RouterInfo", "params": { "i2p.router.id": "", }, "id": 1 } ``` Return: ```json { "jsonrpc": "2.0", "result": "{ data }", "id": 1 } ``` Method - AddressBook -------------------- For the `AddressBook` method, three parameters/arguments are required for deleting and adding entries to the address book: - `Type` - corresponds to address book type: - `private` - `local` - `router` - `published` - `Hostname` - corresponds to the hostname or domain name associated with the address book entry. - `Destination` - corresponds to the destination associated with the address book entry. - `Delete` - this parameter is optional and is used to delete an address book entry. If this parameter is not provided, the method will add a new entry to the address book. Example: ```json { "jsonrpc": "2.0", "method": "AddressBook", "params": { "Type": "private", "Hostname": "example.i2p", "Destination": "exampleDestinationString", "Delete": "" <--- this parameter is optional }, "id": 1 } ``` Return: ```json { "jsonrpc": "2.0", "success": true or false, "message": "Deleted/Added (hostname) in (address book type) address book" OR "Failed to delete/add (hostname) to (address book type) address book", "id": 1 } ``` For editing AddressBookSubscriptions: - `SetSubscriptions` - this parameter is used to set the subscriptions for an address book entry. It takes a list of strings as an argument. Example: ```json { "jsonrpc": "2.0", "method": "AddressBook", "params": { "SetSubscriptions": ["notbob.i2p", "helloworld.i2p", ...] }, "id": 1 } ``` Return: ```json { "jsonrpc": "2.0", "success": true, "message": "Successfully modified: /path/to/subscriptions.txt" } ``` For editing AddressBookConfig: - `SetConfig` - this parameter is used to set the configuration for an address book entry. It takes a JSON object as an argument, which contains the configuration settings. Available/common config parameters: - `subscriptions` - file containing the list of subscription URLs. - `update_delay` - update interval in hours. - `published_addressbook` - path to the published address book. - `router_addressbook` - path to the router address book. - `local_addressbook` - path to the local address book. - `private_addressbook` - path to the private address book. - `proxy_port` - eepProxy port. - `proxy_host` - eepProxy hostname. - `should_publish` - whether to update the published address book. - `etags` - file containing subscription URL etags. - `last_modified` - file containing subscription URL last-modified timestamps. - `log` - log file path. - `theme` - theme. Example: ```json { "jsonrpc": "2.0", "method": "AddressBook", "params": { "SetConfig": { "subscriptions": "subscriptions.txt", "update_delay": "12", "published_addressbook": "../eepsite/docroot/hosts.txt", "router_addressbook": "hosts.txt", "local_addressbook": "../userhosts.txt", "private_addressbook": "../privatehosts.txt", "proxy_port": "4444", "proxy_host": "127.0.0.1", "should_publish": "true", "etags": "etags.txt", "last_modified": "last_modified.txt", "log": "log.txt", "theme": "light" } }, "id": 1 } ``` Return: ```json { "jsonrpc": "2.0", "result": { "success": true, "message": "Successfully modified: /path/to/config.txt" }, "id": 1 } ``` Method - TunnelManager -------- The `TunnelManager` method is used to create, edit, get, start, stop, restart, and delete I2PTunnel controllers. Required parameters: - `Name` - name of the tunnel. This is the tunnel's identifier. - `Action` - action to perform: - `create`. - `edit` - `get` - `start` - `stop` - `restart` - `delete` Optional parameters: - `All` - boolean, whether to apply the action to all tunnels. This is only valid for `start`, `stop`, and `restart` actions. Supported tunnel types for `create`: - `client` - `httpclient` - `ircclient` - `socks` - `socksirc` - `connectclient` - `streamrclient` - `server` - `httpserver` - `httpbidirserver` - `ircserver` - `streamrserver` Common parameters for creating/editing tunnels: - `Type` - tunnel type. Required for `create`. - `NewName` - optional new name when editing. - `Port` - local listen port. - `TargetHost` or `Host` - target host for server tunnels. - `TargetPort` - target port for server tunnels. - `TargetDestination` or `Destination` - destination for client tunnels that require one. - `StartOnLoad` - boolean, whether the tunnel should start when loaded. - `Description` - tunnel description. - `ReachableBy` - interface/address the tunnel listens on. - `Shared` - boolean, whether client tunnel should be shared. - `UseSSL` - boolean, enable SSL where supported. - `TunnelLength` - tunnel length, `0` to `3`. - `TunnelVariance` - tunnel variance, `-2` to `2`. - `TunnelQuantity` - tunnel quantity, `1` to `6`. - `TunnelBackupQuantity` - backup tunnel quantity, `0` to `3`. - `SigType` - signing key type. - `EncType` - encryption type. - `CustomOptions` - custom tunnel options. Client proxy options: - `ProxyList` - `UseOutproxyPlugin` - `ProxyAuth` - `ProxyUsername` - `ProxyPassword` - `OutproxyAuth` - `OutproxyUsername` - `OutproxyPassword` - `OutproxyType` - `SSLProxies` - `JumpList` Client management options: - `ConnectDelay` - `Profile` - `DelayOpen` - `Reduce` - `ReduceCount` - `ReduceTime` - `Close` - `CloseTime` - `NewDest` - `PersistentClientKey` - `PrivKeyFile` HTTP client filtering options: - `AllowUserAgent` - `AllowReferer` - `AllowAccept` - `AllowInternalSSL` Server options: - `WebsiteHostname` or `SpoofedHost` - `BlockAccessInProxies` - `BlockUserAgents` - `UserAgents` - `UniqueLocalAddressPerClient` - `BlockReferers` - `MultiHoming` - `AccessOption` - `AccessList` - `FilterFilePath` - `MaxConcurrentConns` - `ClientPerMinute` - `ClientPerHour` - `ClientPerDay` - `TotalInPerMinute` - `TotalInPerHour` - `TotalInPerDay` - `PostLimit` - `PostLimitTime` - `PerClientPeriod` - `TotalPeriod` - `TotalBanTime` LeaseSet options: - `EncryptLeaseSet` - one of: - `disable` - `encrypted (aes)` - `blinded` - `blinded with lookup password` - `encrypted (psk)` - `encrypted with lookup password (psk)` - `encrypted with per-user key (psk)` - `encrypted with lookup password and per-user key (psk)` - `encrypted with per-user key (dh)` - `encrypted with lookup password and per-user key (dh)` - `OptionalLookup` - `LeaseSetClientAuths` Create example: ```json { "jsonrpc": "2.0", "method": "TunnelManager", "params": { "Name": "example-client", "Action": "create", "Type": "client", "Port": 7656, "TargetDestination": "exampleDestinationString", "StartOnLoad": false, .... }, "id": 1 } ``` Return: ```json { "jsonrpc": "2.0", "result": { "status": "success - created tunnel example-client" OR "error - { error message }", "results": [ {/* information about where persistent keys are stored */} ] }, "id": 1 } ``` Edit example: ```json { "jsonrpc": "2.0", "method": "TunnelManager", "params": { "Name": "example-client", "Action": "edit", "NewName": "renamed-client", "Port": 7657, "TargetDestination": "newDestinationString", "StartOnLoad": true }, "id": 1 } ``` Return: ```json { "jsonrpc": "2.0", "result": { "status": "success - edited tunnel example-client" OR "error - { error message }" }, "id": 1 } ``` Get example: ```json { "jsonrpc": "2.0", "method": "TunnelManager", "params": { "Name": "example-client", "Action": "get" }, "id": 1 } ``` Return: ```json { "jsonrpc": "2.0", "result": { "status": "success - options for example-client" OR "error - { error message }", "info": { "client": true, "status": "running", "persistentClientKey": false, "offlineKeys": false, "targetDestination": "exampleDestinationString", "localDestination": "exampleBase64Destination", "destination": "exampleBase64Destination", "destinationB32": "example.b32.i2p", "rawConfig": { "name": "example-client", "type": "client" } } }, "id": 1 } ``` Start, Stop, Restart, Delete example They follow the same structure, just with different `Action` parameters: ```json { "jsonrpc": "2.0", "method": "TunnelManager", "params": { "Name": "example-client", "Action": "start" }, "id": 1 } ``` Return: ```json { "jsonrpc": "2.0", "result": { "status": "success - starting tunnel example-client" OR "error - { error message }" }, "id": 1 } ``` Method - ClientServicesInfo *(adopted from i2pd)* ------------------------------------------------- The `ClientServicesInfo` method returns status information about client services running on the router. Include the desired service keys (with any value) in `params` to request each service's status. Supported parameters: - `I2PTunnel` - returns a map of configured tunnel names to their addresses, split into `client` and `server` sub-objects. - `HTTPProxy` - returns HTTP proxy enabled state and address. - `SOCKS` - returns SOCKS proxy enabled state and address. - `SAM` - returns SAM bridge enabled state and active session information. - `BOB` - returns BOB bridge enabled state. (Deprecated in Java I2P; always returns `false`.) - `I2CP` - returns I2CP server enabled state. Example: ```json { "jsonrpc": "2.0", "method": "ClientServicesInfo", "params": { "I2PTunnel": "", "SAM": "" }, "id": 1 } ``` Return: ```json { "jsonrpc": "2.0", "result": { "I2PTunnel": { "client": {"my-client": {"address": "example.b32.i2p"}}, "server": {"my-server": {"address": "example.b32.i2p", "port": 8080}} }, "SAM": { "enabled": true, "sessions": {} } }, "id": 1 } ``` Compatibility ============= Compatibility with the existing i2pcontrol API should be maintained, as the new methods and parameters are added in a way that does not interfere with existing functionality. Existing applications using the i2pcontrol API should continue to work without modification, while new applications can take advantage of the additional information and capabilities provided by this proposal. Implementation ============== Java I2P -------- This proposal is not yet implemented in Java I2P, yet the code is available in the [i2p.plugins.i2pcontrol](https://github.com/i2p/i2p.plugins.i2pcontrol) repository under pull request [#6](https://github.com/i2p/i2p.plugins.i2pcontrol/pull/6). This was done to allow for testing and development of the new methods without affecting the existing code. This will be updated into the main I2P repository under i2pcontrol directory once the code is ready for production use. i2pd ---- Methods and parameters marked as "(adopded from i2pd)" are implemented in i2pd and unchanged in this proposal. i2pd's extensions will not require modification as part of this proposal. Unmarked parts of this proposal are not implemented in i2pd. go-i2p ------ go-i2p is motivated to pursue this proposal in order to enable and enhance it's router console application. It will adopt and implement the proposal in the future. emissary -------- Likelihood of adoption in emissary is unknown at this time, however emissary is likely to benefit from this proposal in the same ways as go-i2p. Performance =========== No performance impact expected.