[DOCS] massive documentation update (#20229)
This PR: - reorganizes all documentation pages so they live in the right category - removes lots of legacy docs - contains many improvements to active documentation pages Geth user documentation is now spread across five major categories: - Install and Build: installation and compile instructions - Using Geth: this is for pages about general geth usage. - For dApp Developers: this is for programming guides and functionality specific to dapp development. All the dev guides for mobile framework and Go APIs live here. - JSON-RPC APIs: this has its own section because there is now a sub-page for every name space. I have also added an overview text that explains how to set up the API servers. - For Geth Developers: this is for geth contributors
This commit is contained in:
226
docs/_rpc/ns-admin.md
Normal file
226
docs/_rpc/ns-admin.md
Normal file
@ -0,0 +1,226 @@
|
||||
---
|
||||
title: admin Namespace
|
||||
sort_key: C
|
||||
---
|
||||
|
||||
The `admin` API gives you access to several non-standard RPC methods, which will allow you to have
|
||||
a fine grained control over your Geth instance, including but not limited to network peer and RPC
|
||||
endpoint management.
|
||||
|
||||
* TOC
|
||||
{:toc}
|
||||
|
||||
### admin_addPeer
|
||||
|
||||
The `addPeer` administrative method requests adding a new remote node to the list of tracked static
|
||||
nodes. The node will try to maintain connectivity to these nodes at all times, reconnecting every
|
||||
once in a while if the remote connection goes down.
|
||||
|
||||
The method accepts a single argument, the [`enode`](https://github.com/ethereum/wiki/wiki/enode-url-format)
|
||||
URL of the remote peer to start tracking and returns a `BOOL` indicating whether the peer was accepted
|
||||
for tracking or some error occurred.
|
||||
|
||||
| Client | Method invocation |
|
||||
|:--------|------------------------------------------------|
|
||||
| Go | `admin.AddPeer(url string) (bool, error)` |
|
||||
| Console | `admin.addPeer(url)` |
|
||||
| RPC | `{"method": "admin_addPeer", "params": [url]}` |
|
||||
|
||||
#### Example
|
||||
|
||||
```javascript
|
||||
> admin.addPeer("enode://a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c@52.16.188.185:30303")
|
||||
true
|
||||
```
|
||||
|
||||
### admin_datadir
|
||||
|
||||
The `datadir` administrative property can be queried for the absolute path the running Geth node
|
||||
currently uses to store all its databases.
|
||||
|
||||
| Client | Method invocation |
|
||||
|:--------|-----------------------------------|
|
||||
| Go | `admin.Datadir() (string, error`) |
|
||||
| Console | `admin.datadir` |
|
||||
| RPC | `{"method": "admin_datadir"}` |
|
||||
|
||||
#### Example
|
||||
|
||||
```javascript
|
||||
> admin.datadir
|
||||
"/home/john/.ethereum"
|
||||
```
|
||||
|
||||
### admin_nodeInfo
|
||||
|
||||
The `nodeInfo` administrative property can be queried for all the information known about the running
|
||||
Geth node at the networking granularity. These include general information about the node itself as a
|
||||
participant of the [ÐΞVp2p](https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol) P2P
|
||||
overlay protocol, as well as specialized information added by each of the running application protocols
|
||||
(e.g. `eth`, `les`, `shh`, `bzz`).
|
||||
|
||||
| Client | Method invocation |
|
||||
|:--------|-------------------------------------------|
|
||||
| Go | `admin.NodeInfo() (*p2p.NodeInfo, error`) |
|
||||
| Console | `admin.nodeInfo` |
|
||||
| RPC | `{"method": "admin_nodeInfo"}` |
|
||||
|
||||
#### Example
|
||||
|
||||
```javascript
|
||||
> admin.nodeInfo
|
||||
{
|
||||
enode: "enode://44826a5d6a55f88a18298bca4773fca5749cdc3a5c9f308aa7d810e9b31123f3e7c5fba0b1d70aac5308426f47df2a128a6747040a3815cc7dd7167d03be320d@[::]:30303",
|
||||
id: "44826a5d6a55f88a18298bca4773fca5749cdc3a5c9f308aa7d810e9b31123f3e7c5fba0b1d70aac5308426f47df2a128a6747040a3815cc7dd7167d03be320d",
|
||||
ip: "::",
|
||||
listenAddr: "[::]:30303",
|
||||
name: "Geth/v1.5.0-unstable/linux/go1.6",
|
||||
ports: {
|
||||
discovery: 30303,
|
||||
listener: 30303
|
||||
},
|
||||
protocols: {
|
||||
eth: {
|
||||
difficulty: 17334254859343145000,
|
||||
genesis: "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3",
|
||||
head: "0xb83f73fbe6220c111136aefd27b160bf4a34085c65ba89f24246b3162257c36a",
|
||||
network: 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### admin_peers
|
||||
|
||||
The `peers` administrative property can be queried for all the information known about the connected
|
||||
remote nodes at the networking granularity. These include general information about the nodes themselves
|
||||
as participants of the [ÐΞVp2p](https://github.com/ethereum/wiki/wiki/%C3%90%CE%9EVp2p-Wire-Protocol)
|
||||
P2P overlay protocol, as well as specialized information added by each of the running application
|
||||
protocols (e.g. `eth`, `les`, `shh`, `bzz`).
|
||||
|
||||
| Client | Method invocation |
|
||||
|:--------|------------------------------------------|
|
||||
| Go | `admin.Peers() ([]*p2p.PeerInfo, error`) |
|
||||
| Console | `admin.peers` |
|
||||
| RPC | `{"method": "admin_peers"}` |
|
||||
|
||||
#### Example
|
||||
|
||||
```javascript
|
||||
> admin.peers
|
||||
[{
|
||||
caps: ["eth/61", "eth/62", "eth/63"],
|
||||
id: "08a6b39263470c78d3e4f58e3c997cd2e7af623afce64656cfc56480babcea7a9138f3d09d7b9879344c2d2e457679e3655d4b56eaff5fd4fd7f147bdb045124",
|
||||
name: "Geth/v1.5.0-unstable/linux/go1.5.1",
|
||||
network: {
|
||||
localAddress: "192.168.0.104:51068",
|
||||
remoteAddress: "71.62.31.72:30303"
|
||||
},
|
||||
protocols: {
|
||||
eth: {
|
||||
difficulty: 17334052235346465000,
|
||||
head: "5794b768dae6c6ee5366e6ca7662bdff2882576e09609bf778633e470e0e7852",
|
||||
version: 63
|
||||
}
|
||||
}
|
||||
}, /* ... */ {
|
||||
caps: ["eth/61", "eth/62", "eth/63"],
|
||||
id: "fcad9f6d3faf89a0908a11ddae9d4be3a1039108263b06c96171eb3b0f3ba85a7095a03bb65198c35a04829032d198759edfca9b63a8b69dc47a205d94fce7cc",
|
||||
name: "Geth/v1.3.5-506c9277/linux/go1.4.2",
|
||||
network: {
|
||||
localAddress: "192.168.0.104:55968",
|
||||
remoteAddress: "121.196.232.205:30303"
|
||||
},
|
||||
protocols: {
|
||||
eth: {
|
||||
difficulty: 17335165914080772000,
|
||||
head: "5794b768dae6c6ee5366e6ca7662bdff2882576e09609bf778633e470e0e7852",
|
||||
version: 63
|
||||
}
|
||||
}
|
||||
}]
|
||||
```
|
||||
|
||||
### admin_startRPC
|
||||
|
||||
The `startRPC` administrative method starts an HTTP based [JSON RPC](http://www.jsonrpc.org/specification)
|
||||
API webserver to handle client requests. All the parameters are optional:
|
||||
|
||||
* `host`: network interface to open the listener socket on (defaults to `"localhost"`)
|
||||
* `port`: network port to open the listener socket on (defaults to `8545`)
|
||||
* `cors`: [cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) header to use (defaults to `""`)
|
||||
* `apis`: API modules to offer over this interface (defaults to `"eth,net,web3"`)
|
||||
|
||||
The method returns a boolean flag specifying whether the HTTP RPC listener was opened or not. Please note, only one HTTP endpoint is allowed to be active at any time.
|
||||
|
||||
| Client | Method invocation |
|
||||
|:--------|-----------------------------------------------------------------------------------------------|
|
||||
| Go | `admin.StartRPC(host *string, port *rpc.HexNumber, cors *string, apis *string) (bool, error)` |
|
||||
| Console | `admin.startRPC(host, port, cors, apis)` |
|
||||
| RPC | `{"method": "admin_startRPC", "params": [host, port, cors, apis]}` |
|
||||
|
||||
#### Example
|
||||
|
||||
```javascript
|
||||
> admin.startRPC("127.0.0.1", 8545)
|
||||
true
|
||||
```
|
||||
|
||||
### admin_startWS
|
||||
|
||||
The `startWS` administrative method starts an WebSocket based [JSON RPC](http://www.jsonrpc.org/specification)
|
||||
API webserver to handle client requests. All the parameters are optional:
|
||||
|
||||
* `host`: network interface to open the listener socket on (defaults to `"localhost"`)
|
||||
* `port`: network port to open the listener socket on (defaults to `8546`)
|
||||
* `cors`: [cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) header to use (defaults to `""`)
|
||||
* `apis`: API modules to offer over this interface (defaults to `"eth,net,web3"`)
|
||||
|
||||
The method returns a boolean flag specifying whether the WebSocket RPC listener was opened or not. Please note, only one WebSocket endpoint is allowed to be active at any time.
|
||||
|
||||
| Client | Method invocation |
|
||||
|:--------|-----------------------------------------------------------------------------------------------|
|
||||
| Go | `admin.StartWS(host *string, port *rpc.HexNumber, cors *string, apis *string) (bool, error)` |
|
||||
| Console | `admin.startWS(host, port, cors, apis)` |
|
||||
| RPC | `{"method": "admin_startWS", "params": [host, port, cors, apis]}` |
|
||||
|
||||
#### Example
|
||||
|
||||
```javascript
|
||||
> admin.startWS("127.0.0.1", 8546)
|
||||
true
|
||||
```
|
||||
|
||||
### admin_stopRPC
|
||||
|
||||
The `stopRPC` administrative method closes the currently open HTTP RPC endpoint. As the node can only have a single HTTP endpoint running, this method takes no parameters, returning a boolean whether the endpoint was closed or not.
|
||||
|
||||
| Client | Method invocation |
|
||||
|:--------|---------------------------------|
|
||||
| Go | `admin.StopRPC() (bool, error`) |
|
||||
| Console | `admin.stopRPC()` |
|
||||
| RPC | `{"method": "admin_stopRPC"` |
|
||||
|
||||
#### Example
|
||||
|
||||
```javascript
|
||||
> admin.stopRPC()
|
||||
true
|
||||
```
|
||||
|
||||
### admin_stopWS
|
||||
|
||||
The `stopWS` administrative method closes the currently open WebSocket RPC endpoint. As the node can only have a single WebSocket endpoint running, this method takes no parameters, returning a boolean whether the endpoint was closed or not.
|
||||
|
||||
| Client | Method invocation |
|
||||
|:--------|--------------------------------|
|
||||
| Go | `admin.StopWS() (bool, error`) |
|
||||
| Console | `admin.stopWS()` |
|
||||
| RPC | `{"method": "admin_stopWS"` |
|
||||
|
||||
#### Example
|
||||
|
||||
```javascript
|
||||
> admin.stopWS()
|
||||
true
|
||||
```
|
Reference in New Issue
Block a user